PATTERNS_BACKEND_STANDARD - TheDaniel166/moira GitHub Wiki

Moira Patterns Backend Standard

Governing Principle

The Moira patterns backend is a sovereign computational subsystem. Its definitions, layer boundaries, terminology, 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 through the structural-role and dominant-containment admission. It describes the subsystem that actually exists in moira/patterns.py; it does not describe aspirational future capabilities.

The separate moira.stelliums.analyze_stelliums product now owns planet-first Strict/Broad sign, house and total-span concentration evidence. See STELLIUM_ANALYSIS_STANDARD.md. This document's legacy centroid-based Stellium, default count, aspect-contribution and condition semantics are unchanged; they must not be silently presented as the new product.

Part I - Architecture Standard

1. Authoritative Computational Definitions

1.1 Core pattern computation

An aspect pattern in Moira is:

The authoritative result of one of the pattern detectors in moira.patterns, or of find_all_patterns, computed from admitted AspectData relations and, for Stellium, position clustering doctrine.

The computational core remains the authority for:

  • detector admission
  • orb arithmetic
  • aspect-map lookup
  • body ordering inside each detected pattern
  • stellium centroid and spread arithmetic
  • duplicate suppression
  • opt-in cross-detector structural-containment filtering

Later layers may preserve, classify, inspect, aggregate, or network this truth. They may not recompute pattern doctrine independently.

1.2 Pattern vessel

An AspectPattern in Moira is:

The canonical per-pattern result vessel representing one detected multi-body configuration, including its pattern name, bodies, contributing aspects, optional apex, preserved truth, classifications, contribution relations, and derived condition profile.

AspectPattern is the authoritative local truth vessel for this subsystem.

1.3 Detection truth

A pattern detection truth in Moira is:

The preserved doctrinal and computational path describing which detector matched, whether the pattern was aspect- or position-driven, and which body roles the detector assigned.

This truth is carried by AspectPattern.detection_truth. It is descriptive only. It does not alter detector semantics.

1.4 Contribution

A pattern contribution in Moira is:

One formal relational record describing how an admitted aspect participates inside one detected pattern.

The contribution layer distinguishes:

Term Definition
all_contributions full preserved contribution surface for the pattern
contributions the currently admitted contribution subset
pattern_contributions(...) flattened admitted contribution view
all_pattern_contributions(...) flattened full preserved contribution view

Under the current default doctrine, contributions == all_contributions.

1.5 Pattern condition profile

A pattern condition profile in Moira is:

A backend-only integrated structural summary derived from one AspectPattern, combining classification and contribution structure into one per-pattern condition vessel.

PatternConditionProfile is derived only from lower-layer truth. It is not a second pattern engine.

Its state names describe role-resolution completeness only:

State Structural meaning
reinforced every preserved contributing aspect has a detector-owned structural role
mixed at least one preserved contribution remains the generic member_link
weakened the pattern has no aspect contributions, as with the position-based Stellium

These states do not measure harmony, exactness, applying/separating motion, or interpretive strength. AspectData.applying is not an input to this profile.

1.6 Pattern chart condition profile

A pattern chart condition profile in Moira is:

A deterministic chart-wide aggregation of per-pattern condition profiles, reporting structural counts, contribution totals, and strongest / weakest pattern summaries under the currently embodied ranking.

1.7 Pattern condition network profile

A pattern condition network profile in Moira is:

A deterministic graph projection over detected pattern instances and their participating bodies, derived from existing pattern and condition truth.

It includes at least:

  • one node per detected pattern instance
  • one node per participating body
  • one directed edge per pattern-to-body participation link
  • incoming / outgoing / total degree counts per node
  • isolated bodies
  • direct-degree connectivity summaries

This is a structural backend layer only. It is not interpretation.

2. Layer Structure

The backend is organised into one computational core plus ten formalised post-core layers. Each layer consumes outputs already produced below it. No layer reaches upward.

Core      - Authoritative pattern computation (`find_all_patterns`)
Phase  1  - Truth preservation
Phase  2  - Classification
Phase  3  - Inspectability and vessel hardening
Phase  4  - Doctrine / policy surface
Phase  5  - Contribution formalisation
Phase  6  - Contribution inspectability / hardening
Phase  7  - Integrated per-pattern condition
Phase  8  - Chart-wide condition intelligence
Phase  9  - Pattern / condition network intelligence
Phase 10  - Full-subsystem hardening
Phase 11  - Architecture freeze / validation codex

Layer boundary rules

A layer above the core:

  • may consume preserved truth from lower layers
  • may classify or aggregate earlier truth
  • may add invariant checks that reject internally inconsistent vessels
  • may not recompute detector doctrine independently
  • may not alter legacy pattern admission semantics by reclassification
  • may not mutate an earlier-layer vessel in place
  • may not introduce interpretation, recommendation, or UI concerns

3. Delegated Assumptions

The patterns backend delegates to external modules without redefining them:

Concern Delegated to Convention
aspect computation moira.aspects.find_aspects returns admitted AspectData instances
aspect vessel truth moira.aspects.AspectData authoritative aspect endpoint / angle / orb data
circular distance arithmetic moira.coordinates.angular_distance authoritative angular-separation helper

Changes to those delegated sources propagate into the patterns subsystem. This document does not freeze their independent doctrine.

4. Doctrine Surface

4.1 Detector doctrine

Pattern doctrine begins with the detector set embodied in moira/patterns.py. The current subsystem includes:

  • classical and mainstream pattern detectors
  • extended geometric / Huber-recognized detectors already implemented
  • harmonic 5th- and 7th-harmonic detectors already implemented
  • stellium position clustering doctrine

No additional detector doctrine is implied by this document.

4.2 Orb doctrine

Pattern orb doctrine is embodied by:

  • detector-specific fixed base orbs
  • the caller-visible orb_factor
  • current Stellium orb and min_bodies doctrine

The default policy preserves unfiltered detector admission: all registered detectors are selected and cross-detector containment is disabled.

4.3 Policy doctrine

PatternComputationPolicy makes current doctrine explicit without changing the default result.

Policy area Type Current default
named detector selection PatternSelectionPolicy all registered patterns admitted
Stellium doctrine StelliumPolicy min_bodies=3, orb=8.0
global orb scaling PatternComputationPolicy.orb_factor 1.0
cross-detector containment PatternComputationPolicy.dominant_only False

The normative default is:

PatternComputationPolicy() must preserve the current unfiltered admission behavior exactly.

4.4 Dominant-containment doctrine

When dominant_only=True, a detected aspect pattern is omitted only when it is a strict structural subgraph of another admitted aspect pattern. This requires:

  • both patterns to be aspect-sourced
  • inclusion of the smaller pattern's body set in the container's body set
  • at least one contribution in the smaller pattern
  • inclusion of every smaller-pattern aspect signature in the larger pattern's full preserved aspect surface
  • strict inclusion in at least one dimension: bodies or aspect signatures

Body count alone is not containment. Equal-body patterns remain present when their aspect surfaces are equal or incomparable, but an equal-body strict edge subgraph such as Trapeze inside Cradle is omitted. Position-sourced Stelliums remain incomparable with aspect patterns and retain their detector-local maximal-group rule. Dominance is evaluated only among detectors admitted by the current selection policy, so an excluded container cannot hide a requested subpattern.

5. Classification

PatternClassification is descriptive only. It classifies:

  • source kind
  • symmetry kind
  • body count
  • apex presence
  • typed body roles

PatternAspectRoleKind classifies contribution roles descriptively only.

Detector-owned symmetric topology is preserved without arbitrary left/right labels:

  • Grand Trine bodies are cycle_member; all three trines are cycle_link.
  • Minor Grand Trine preserves its public symmetric/no-apex contract: the trine endpoints are base, the two-sextile focus is support, and its links are one base_link plus two support_link records.
  • Cradle and Trapeze opposition endpoints are axis; the remaining bodies are support, producing one axis_link and structured support links. The admitted Trapeze graph is specifically a three-sextile chain with its two end bodies in opposition; it is not the six-edge Cradle graph.
  • Grand Cross and Mystic Rectangle bodies are cycle_member; opposition diagonals are axis_link and perimeter relations are cycle_link.
  • Septile Triangle bodies and its three harmonic boundary relations are cycle_member and cycle_link respectively.

These assignments follow detector-proved graph roles. There is no blanket rule that relabels every no-apex pattern as structured.

Classification describes preserved truth. It does not affect detector admission, orb arithmetic, or pattern semantics.

6. Inspectability

AspectPattern exposes derived inspectability helpers so callers do not need to reconstruct structure from nested truth:

  • detector
  • source_kind
  • symmetry_kind
  • body_role_kinds
  • is_position_based
  • is_apex_bearing
  • contribution_roles
  • admitted_contributions
  • all_contribution_roles
  • contribution_count
  • all_contribution_count
  • has_contributions
  • condition_state

The chart and network layers also expose small derived inspectability helpers:

  • PatternChartConditionProfile.profile_count
  • PatternChartConditionProfile.strongest_count
  • PatternChartConditionProfile.weakest_count
  • PatternConditionNetworkProfile.node_count
  • PatternConditionNetworkProfile.edge_count

These properties are derived only. They do not change doctrine.

7. Failure Doctrine

7.1 Input failure behavior

Malformed raw inputs must fail clearly and deterministically before pattern computation proceeds.

Current explicit failures include:

  • empty body names in positions
  • non-finite position longitudes
  • malformed aspect endpoints
  • self-aspects in supplied aspects
  • non-finite aspect angles or orbs
  • negative aspect orbs
  • invalid min_bodies
  • invalid Stellium orb values
  • invalid global orb_factor
  • malformed policy objects
  • repeated selection names
  • unsupported selection names
  • non-boolean dominant-only policy

7.2 Internal inconsistency behavior

If a vessel is constructed with internally inconsistent truth, classification, contribution, condition, chart, or network state, it must fail loudly with ValueError.

Silent internal drift is prohibited.

8. Determinism Guarantees

For identical validated inputs and policy, the subsystem guarantees:

  • deterministic pattern inclusion / omission
  • deterministic maximal structural-containment filtering when requested
  • deterministic pattern ordering
  • deterministic body-role preservation
  • deterministic contribution ordering
  • deterministic condition-profile ordering
  • deterministic chart strongest / weakest summaries
  • deterministic network node ordering
  • deterministic network edge ordering
  • deterministic isolated / most-connected summaries

No public result vessel may depend on hash order or incidental iteration order.

Part II - Invariant Register

9. Vessel Invariants

The following invariants are normative.

9.1 PatternDetectionTruth

  • source_kind must be one of the currently supported detector sources
  • body_roles must not be empty
  • body_roles must not repeat bodies
  • position-based truth must preserve centroid, spread, and orb limit

9.2 PatternClassification

  • body_count must match body_roles
  • body_roles must not repeat bodies
  • has_apex must agree with body roles

9.3 PatternAspectContribution

  • contribution endpoints must differ
  • contribution endpoints must match the bound aspect endpoints
  • aspect_name must match aspect.aspect
  • aspect_angle must match aspect.angle

9.4 PatternConditionProfile

  • body_count must be positive
  • contribution counts must be non-negative
  • contribution_count must not exceed all_contribution_count
  • structured and generic counts must cover all_contributions
  • has_apex must match symmetry
  • state must match the derived contribution structure

9.5 AspectPattern

  • bodies must not be empty
  • apex, when present, must be one of the bodies
  • preserved truth must agree with the pattern name and body set
  • classification must agree with preserved truth
  • all_contributions must match pattern aspects exactly
  • contributions must be a subset of all_contributions
  • under the current doctrine, contributions must match all_contributions
  • contribution relations must not repeat the same aspect relation
  • condition_profile must agree with classification and contribution truth

9.6 PatternChartConditionProfile

  • state counts must match profile states
  • contribution totals must match profile totals
  • profiles must be in deterministic order
  • strongest_patterns must match the derived strongest ranking
  • weakest_patterns must match the derived weakest ranking

9.7 PatternConditionNetworkNode

  • kind must be one of the currently supported node kinds
  • total degree must equal incoming plus outgoing degree

9.8 PatternConditionNetworkEdge

  • source and target ids must differ

9.9 PatternConditionNetworkProfile

  • nodes must be in deterministic order
  • edges must be in deterministic order
  • node ids must be unique
  • edges must reference existing nodes
  • node incoming and outgoing counts must match the edges
  • isolated_bodies must match body nodes with zero degree
  • most_connected_nodes must match the highest total degree

Part III - Public Surface and Validation Codex

10. Stable Public Surface

The stable patterns backend surface is the combination of:

  • result vessels:
    • AspectPattern
    • PatternBodyRoleTruth
    • PatternDetectionTruth
    • PatternBodyRoleClassification
    • PatternClassification
    • PatternAspectContribution
    • PatternConditionProfile
    • PatternChartConditionProfile
    • PatternConditionNetworkNode
    • PatternConditionNetworkEdge
    • PatternConditionNetworkProfile
  • enums:
    • PatternSourceKind
    • PatternSymmetryKind
    • PatternBodyRoleKind
    • PatternAspectRoleKind
    • PatternConditionState
  • policy types:
    • PatternSelectionPolicy
    • StelliumPolicy
    • PatternComputationPolicy
  • module entrypoints:
    • find_all_patterns
    • find_stelliums
    • pattern_contributions
    • all_pattern_contributions
    • pattern_condition_profiles
    • pattern_chart_condition_profile
    • pattern_condition_network_profile

Internal helpers remain implementation detail unless explicitly exported later.

11. Minimum Validation Codex

Any substantive change to moira/patterns.py must, at minimum, preserve:

  1. detector admission and pattern semantics
  2. structured truth consistency
  3. classification consistency
  4. contribution consistency
  5. condition-profile consistency
  6. chart-profile consistency
  7. network consistency
  8. deterministic failure behavior

Minimum validation commands:

.\.venv\Scripts\python.exe -m pytest tests\unit\test_patterns.py -q
.\.venv\Scripts\python.exe -m pytest tests\unit\test_pattern_facade.py tests\server\test_server_patterns_policy.py -q
.\.venv\Scripts\python.exe -m pytest tests\unit\test_aspects.py -q -k "find_patterns or public_api"
.\.venv\Scripts\python.exe -m py_compile moira\patterns.py tests\unit\test_patterns.py

If the public package surface changes later, the matching API-freeze test must also be included in the minimum validation set.

12. Non-Goals Frozen By This Standard

The current patterns backend does not include:

  • interpretation of pattern meaning
  • recommendation or judgment logic
  • chart-wide interpretive synthesis
  • UI or rendering concerns
  • probabilistic confidence scoring
  • pattern-to-pattern doctrinal inference beyond the explicit optional structural-containment filter

Those concerns belong to later layers or different subsystems. They are not part of the current constitutional backend.