PRIMARY_DIRECTIONS_BACKEND_STANDARD - TheDaniel166/moira GitHub Wiki

Moira Primary Directions Backend Standard

Constitutional Phase: 13 - Chronological projection and transport hardening Status: Admitted runtime standard; external authority validation remains product- and branch-scoped

Governing Principle

The Moira primary-directions backend is a Moira-owned doctrinal subsystem.

Its authoritative computational surface is the currently admitted recoverable surface, not the older Placidian-only narrow branch.

This standard therefore describes the subsystem as it actually exists now:

  • multiple admitted geometry families
  • In Mundo and In Zodiaco
  • direct, traditional role-exchange converse, opt-in neo-converse, and one narrow signed-primary-motion doctrine
  • explicit relation doctrine
  • explicit preset doctrine
  • validated narrow target-family expansions
  • static and dynamic key doctrine plus an integrated chronological timeline

This is an implementation and compatibility standard, not a claim that every historical branch has primary-authority validation. It does not freeze deferred or unresolved frontiers such as:

  • field_plane
  • wider midpoint doctrine beyond the admitted shortest-arc target construction
  • wider mundane-aspect laws beyond the admitted Placidian and Ptolemaic branches
  • wider non-sovereign frontier branches

Part I - Architecture Standard

1. Authoritative Computational Definitions

1.1 Speculum entry

A speculum entry in Moira is:

The authoritative directional state of one natal body, angle, star, or derived directed point under an admitted primary-direction branch, including the equatorial and directional quantities required by that branch.

For the currently admitted recoverable surface, this includes the Placidian mundane substrate and the projected/equatorial or under-the-pole quantities required by the admitted geometry families.

1.2 Primary arc

A primary arc in Moira is:

A positive directional arc measuring the amount of primary motion required for the admitted promissor to perfect the admitted relation to the admitted significator under one explicit method, space, motion doctrine, and key.

The arc also carries its actual positional relation kind. A bodily promissor is conjunction; an explicitly derived opposition, aspect, parallel, reflected point, or rapt-parallel carries that distinct relation kind.

1.3 Relation

A primary-direction relation is:

The typed doctrinal interpretation of one PrimaryArc under explicit method, space, relation, motion, latitude, and key doctrine.

relational_kind names the positional relation. The compatibility relation_kind field names the perfection kind; perfection_kind is its explicit alias. These are separate public truths and must not be conflated.

1.4 Local condition

A local condition profile is:

The integrated per-significator view of all admitted primary arcs directed to that significator within one computed result set.

1.5 Aggregate profile

An aggregate profile is:

The chart-wide summary over all per-significator primary-direction profiles.

1.6 Network profile

A network profile is:

The directed promissor-to-significator graph induced by the current arc set.

The separate method, perfection, relation, and target transition-network vessels summarize one ordered input sequence. Their aggregate edges must be realizable as one connected directed Euler trail after adjacent self- transitions are suppressed; a balanced circuit must have enough node occurrences to be linearized. Count conservation alone is not sufficient.

2. Layer Structure

The backend is organized into the following implemented phases:

Phase  1 - Truth preservation        (SpeculumEntry, PrimaryArc, speculum, find_primary_arcs)
Phase  2 - Classification            (typed method/space/motion/key/relation doctrine)
Phase  3 - Inspectability            (vessel invariants and helper properties)
Phase  4 - Policy surface            (PrimaryDirectionsPolicy, presets, target/relation gating)
Phase  5 - Relational formalization  (PrimaryDirectionRelation, relate_primary_arc)
Phase  6 - Relation hardening        (PrimaryDirectionRelationProfile, evaluate_primary_direction_relations)
Phase  7 - Local condition           (PrimaryDirectionsSignificatorProfile, evaluate_primary_direction_condition)
Phase  8 - Aggregate intelligence    (PrimaryDirectionsAggregateProfile, evaluate_primary_directions_aggregate)
Phase  9 - Network intelligence      (PrimaryDirectionsNetworkProfile, evaluate_primary_directions_network)
Phase 10 - Full hardening            (cross-layer invariants, deterministic ordering, failure contracts)
Phase 11 - Backend standard          (runtime standard and scoped validation codex)
Phase 12 - Public API curation       (engine, facade, and stable transport verification)
Phase 13 - Chronological projection  (dynamic keys, bounds, distributors, participators)

Layer boundary rules:

  • later phases may consume lower-phase vessels
  • later phases may not silently mutate lower-phase vessels
  • later phases may not switch doctrine implicitly
  • later phases may not widen beyond the admitted recoverable surface without explicit constitutional revision

3. Current Doctrine Surface

3.1 Admitted methods

Current runtime-admitted methods:

  • PLACIDUS_MUNDANE
  • PTOLEMY_SEMI_ARC
  • PLACIDIAN_CLASSIC_SEMI_ARC
  • MERIDIAN
  • MORINUS
  • REGIOMONTANUS
  • CAMPANUS
  • TOPOCENTRIC

Important qualifier:

  • PLACIDUS_MUNDANE and PLACIDIAN_CLASSIC_SEMI_ARC are mundane-only runtime methods. Policy construction, PrimaryArc, and geometry dispatch reject an IN_ZODIACO pairing instead of labeling mundane geometry as zodiacal.
  • PTOLEMY_SEMI_ARC remains both mundane- and zodiacal-capable under its named branch policies.
  • MORINUS is admitted with an explicit doctrinal limit
    • the aspect-plane branch is distinct and source-backed when the required context is supplied
    • the conjunction-style branch follows Morin's circle-of-position treatment and currently shares the Regiomontanus under-the-pole runtime law
    • supplied aspect contexts use normalized, non-empty source_name identity, must be unique by that exact source identity, and fail closed on invalid or impossible path context

3.2 Admitted spaces

Current runtime-admitted spaces:

  • IN_MUNDO
  • IN_ZODIACO

Not admitted:

  • FIELD_PLANE

3.3 Motion doctrine

Current admitted motion doctrines:

  • DIRECT_ONLY
  • TRADITIONAL_CONVERSE
  • NEO_CONVERSE
  • SIGNED_PRIMARY_MOTION, only through TOPOCENTRIC_ZODIACAL_ASPECT_SIGNED_PRIMARY_MOTION

TRADITIONAL_CONVERSE preserves the established construction: direct and converse are separate ordered calculations with promissor and significator roles exchanged. The signed-primary-motion preset does not alter that product. It constructs one ordered Topocentric zodiacal-aspect arc with assigned-zero aspect latitude and projected perfection, wraps it to the unique signed shortest displacement in (-180, 180) degrees, and classifies a positive arc as direct or a negative arc as converse. Numerical coincidence is no event; an exact or tolerance-coalesced 180-degree displacement has no unique sign and fails closed. In this preset, include_converse=True admits either label from that one construction; it does not request a second role-exchanged arc. Searches under this doctrine require explicit, non-empty significator and promissor filters. The unrestricted target set contains the antipodal MC/IC pair, whose direction is intentionally undefined rather than silently skipped.

NEO_CONVERSE is an explicit opt-in doctrine. It keeps the significator as receiver and directs the promissor against diurnal rotation by the circle- complement law (360 degrees - direct_arc) mod 360 degrees. It is distinct from traditional role exchange on asymmetric semi-arc systems and may coincide with it on symmetric equatorial systems. REST callers select it through the typed converse_doctrine policy field; contradictory include_converse requests fail validation.

SIGNED_PRIMARY_MOTION is not NEO_CONVERSE. It is a source-scoped sign classification for one named Topocentric branch, not a global direction against diurnal rotation and not a generic method-wide converse toggle.

3.4 Time-key doctrine

Current admitted keys:

  • PTOLEMY
  • NAIBOD
  • CARDAN
  • SOLAR
  • SOLAR_RA_DYNAMIC
  • SOLAR_LON_DYNAMIC

Keys remain orthogonal to method and space.

The SOLAR key is a static conversion using one explicit positive natal solar rate. It is not a dynamic solar-arc integration, and it fails closed when that rate is unavailable. PrimaryArc retains a positive numeric compatibility rate for arcs constructed without a rate, but solar_rate_explicit=False marks that value as unavailable to solar-key conversion; generated arcs and explicitly supplied natal rates report solar_rate_explicit=True. The low-level key resolver retains its historical, inspectable unknown-string-to-Naibod adapter; typed facade and REST policy surfaces reject unsupported or ambiguous key values.

SOLAR_RA_DYNAMIC and SOLAR_LON_DYNAMIC invert actual solar motion from the natal Julian date through the planetary reader. Missing natal time, unavailable ephemeris state, or inversion failure raises. A dynamic request is never silently converted with a static solar or Naibod rate.

3.5 Relation doctrine

Current explicit relation classes:

  • conjunction
  • opposition
  • zodiacal_aspect
  • parallel
  • contra_parallel
  • rapt_parallel
  • antiscion
  • contra_antiscion
  • term_bound
  • mundane_aspect
  • mundane_parallel
  • mundane_contra_parallel
  • midpoint

3.6 Target doctrine

Current base target families:

  • planets
  • nodes
  • angles
  • house cusps

Current narrow admitted derived or expanded families:

  • zodiacal aspect-point promissors
  • Ptolemaic zodiacal parallels / contra-parallels
  • Placidian direct and converse rapt parallels
  • catalog-backed fixed-star conjunctions to angles and planets
  • Ptolemaic zodiacal antiscia / contra-antiscia
  • term/bound boundaries used by distributor chronology
  • method-scoped Placidian and Ptolemaic mundane aspect points
  • Placidian mundane parallels / contra-parallels
  • shortest-arc circular midpoint promissors

Configured fixed stars are admitted only when conjunction is admitted. Rapt parallel motion is relation-specific: its explicit direct or converse motion applies to the configured rapt targets and does not widen the ambient policy's ordinary motions or conjunction targets. When a named aspectual promissor is sourced from a house cusp, the source cusp is materialized as a directional entry before the aspect point is projected.

4. Public Surface

Current owning public module:

  • moira.primary_directions

Current curated public surface includes:

  • doctrine enums and policy types
  • SpeculumEntry
  • PrimaryArc
  • relation/profile/aggregate/network vessels
  • branch preset types and preset builders
  • narrow target wrapper types for admitted derived families
  • speculum
  • find_primary_arcs
  • relation/profile/aggregate/network evaluation helpers

The Moira facade preserves the established speculum(...) and primary_directions(...) positional calls and adds keyword-only doctrine inputs plus policy-preset, relation, condition, aggregate-profile, and network delegations. The nine existing /v1/primary-directions/* paths (including the integrated chronological life timeline endpoint) are transport surfaces over these engine meanings; route code does not own doctrine. The seven search-derived paths accept additive typed vessels for the admitted antiscia, Ptolemaic-parallel, Placidian-rapt-parallel, fixed-star, mundane- aspect, mundane-parallel, midpoint, and Morinus aspect-context branches. Transport resolution must construct the existing engine vessels explicitly, enforce the branch/preset compatibility matrix, and report the exact resolved configuration on reduction responses. Those search inputs are not accepted by submitted-arc evaluation, which has no target-materialization stage. The timeline path additionally reports the applied bounds doctrine and motion on every distributor period.

The signed-primary-motion preset is likewise engine-search-only at the REST boundary. Submitted arcs already carry a positive magnitude and direct or converse label, but not the ordered raw arc required to derive that label; therefore the submitted-only relations path and any search request containing submitted_arcs reject this preset rather than pretending to reclassify it.

The thin root package moira does not re-export these internals.

Part II - Invariants and Failure Doctrine

5. Structural invariants

The governing invariant register for this subsystem is:

SpeculumEntry invariants:

  • all scalar fields are finite real values, not booleans or coercive strings
  • normalized angular quantities remain normalized
  • declination remains within [-90, 90]
  • semi-arc structure remains internally consistent where applicable
  • a zero-semi-arc limiting tangent and a no-real rise/set geometry fail closed
  • branch-specific directional quantities must agree with the active geometry law

PrimaryArc invariants:

  • non-empty significator and promissor
  • no self-directions
  • positive arc
  • positive stored solar rate plus explicit provenance distinguishing a usable natal solar rate from the compatibility value
  • direction agrees with motion doctrine
  • admitted method and space only, including method/space capability agreement
  • a typed positional relational_kind
  • relation kind must be compatible with the requested promissor family
  • target family must be compatible with the active branch preset and target policy

Cross-layer invariants:

  • lower-layer ownership consistency is enforced
  • OA(ASC) supplied to Placidian-classic endpoint geometry is the equatorial horizon coordinate (ARMC + 90 degrees) mod 360, not the right ascension of the ecliptic Ascendant
  • relation perfection kind agrees with the arc's space; detected, admitted, and scored relations belong to the profile's owning arc; significator relation profiles preserve arc order and identity
  • aggregate counts must equal profile-derived counts
  • network edges may not dangle
  • node names must be unique
  • branch presets may not silently widen relation or target doctrine
  • derived target families must be realized only through the method-specific law that admits them
  • signed-primary-motion may be materialized only by its explicit Topocentric zodiacal-aspect preset, with assigned-zero latitude and projected perfection
  • signed-primary-motion search requires explicit non-empty significator and promissor filters; an explicitly requested antipodal pair still fails closed
  • ordered method/perfection/relation/target transition counts must describe one connected, degree-valid directed path or lawfully linearizable circuit

6. Failure doctrine

Current policy:

  • invalid doctrine raises ValueError
  • invalid vessel state raises ValueError
  • invalid preset-target or preset-relation combinations raise ValueError
  • signed-primary-motion coincidence produces no event, while its directionally ambiguous 180-degree boundary raises ValueError
  • method/space combinations outside a method's declared capability raise ValueError
  • empty engine aggregate/network/profile requests raise ValueError; REST search routes represent a lawful no-match result with transport-owned empty response vessels rather than constructing invalid engine vessels

No silent fallback is allowed for unsupported method, space, motion doctrine, key doctrine, bounds doctrine, target family, or relation family.

Part III - Determinism and Validation

7. Determinism

Current deterministic guarantees:

  • find_primary_arcs() sorts by (arc, significator, promissor, direction)
  • significator profiles sort by (significator, nearest_arc)
  • network nodes sort by name
  • network edges sort by (nearest_arc, promissor, significator)
  • timeline events sort by (age, arc, significator, promissor)
  • distributor periods sort by (entry_age, significator, motion, entry_arc, exit_arc, ruler) and retain their direct or converse motion identity
  • fixture-backed narrow families preserve exact reconstruction and published rounded values separately where needed

The runtime spherical laws preserve quadrant continuity. Inverse-trigonometric branches accept only round-off-sized excursions beyond their real domain and otherwise fail closed; there are no post-hoc quadrant flips or fabricated polar solutions.

8. Validation codex

The governing validation codex for this subsystem is:

Minimum verification for the currently admitted recoverable surface should include:

.\.venv\Scripts\python.exe -m compileall -q moira\primary_directions moira\_facade_special.py moira_server\models\primary_directions.py moira_server\services\primary_directions.py moira_server\serializers\primary_directions.py moira_server\routers\primary_directions.py
$tests = Get-ChildItem tests\unit -Filter 'test_primary_direction*.py' | ForEach-Object { $_.FullName }
.\.venv\Scripts\python.exe -m pytest $tests -q
.\.venv\Scripts\python.exe -m pytest tests\server\test_server_phase8_primary_directions_routes.py -q
.\.venv\Scripts\python.exe -m pytest tests\server\test_server_primary_directions_timeline_routes.py -q

These checks are expected to verify:

  • core speculum arithmetic
  • geometry-law routing
  • doctrine and preset invariants
  • relation and target-family gating
  • relation/profile/aggregate/network layers
  • admitted narrow-family fixture validations
  • curated public API surface
  • stable route discovery, submitted-arc reconstruction, empty transport responses, and engine/REST doctrine parity

The evidence classes must remain explicit. The Hemminga Mars-to-Jupiter example is a named historical-authority comparison. Published Makransky examples constrain the shared narrow Campanus-Regiomontanus conjunction law and the Topocentric under-the-pole law under their printed-input tolerances; the latter source's signed direct/converse naming is admitted only through the separate signed-primary-motion preset and does not rewrite Moira's established role-exchange doctrine. Lilly's printed fixed-star and zero-latitude antiscion rows constrain only those historical zodiacal products. Leo/Sepharial declination-equivalent and rapt examples, and the modern Morinus circle-of-aspects calculation, remain branch-scoped evidence under their declared source classes. Internal catalog/DE441 reconstructions remain regression or substrate evidence. None of these narrower artifacts proves all methods, targets, epochs, latitudes, or historical schools.

Part IV - Frontier Boundary

9. What remains outside the current freeze

The following remain outside this backend standard:

  • FIELD_PLANE
  • fixed-star opposition and wider star aspects
  • wider non-Placidian parallel families
  • wider non-Ptolemaic reflected doctrine
  • wider midpoint doctrines beyond the admitted shortest-arc target
  • wider mundane-aspect laws beyond the admitted Placidian and Ptolemaic branches
  • unresolved method-specific frontier branches documented in the remaining frontier packet

These belong to later doctrinal admission work, not to the current frozen recoverable surface.