luna_common — Foundation Package

The lingua franca. Schemas, constants, and consciousness model for the Luna ecosystem.

luna_common is the shared mathematical foundation of the Luna ecosystem. It defines the φ-derived constants, consciousness dynamics, quality scoring engine, and Pydantic schemas. Luna is a single autonomous agent — Perception, Reflection, Integration, Expression are four cognitive faculties of one system. The external projects (SAYOHMY, SENTINEL, TESTENGINEER) are independent agents that import their identity profiles from here.

Version: 5.3

---

Architecture

luna_common/
├── __init__.py
├── constants.py                # All φ-derived constants
├── consciousness/              # Consciousness dynamics
│   ├── simplex.py              # Softmax simplex projection (τ = φ)
│   ├── matrices.py             # Γ temporal, spatial, info matrices
│   ├── evolution.py            # Consciousness evolution step
│   ├── context.py              # Execution context builder (∂ᶜ)
│   ├── profiles.py             # Agent identity profiles (Ψ₀)
│   ├── illusion.py             # Illusion detection (self + system)
│   └── affect_constants.py     # Affect system constants (φ-derived)
├── phi_engine/                 # Quality scoring engine
│   ├── scorer.py               # PhiScorer — Fibonacci-weighted EMA
│   ├── convergence.py          # Convergence detector
│   ├── phase_transition.py     # Phase state machine with hysteresis
│   ├── soft_constraint.py      # Fibonacci zone constraints
│   └── veto.py                 # Veto system (rules + resolution)
└── schemas/                    # Shared data contracts
    ├── pipeline.py             # PsiState, InfoGradient, CurrentTask, IntegrationCheck, Decision
    ├── metrics.py              # NormalizedMetricsReport, VerdictInput
    ├── signals.py              # SleepNotification, KillSignal, VitalsRequest, VitalsReport, AuditEntry
    └── cycle.py                # CycleRecord, RewardVector, TelemetrySummary, VoiceDelta

Constants

All values derive from a single constant: φ = (1 + √5) / 2 = 1.618…

PHI      = 1.618033988749895   # The golden ratio
INV_PHI  = 1/φ   = 0.618      # Time step (dt)
INV_PHI2 = 1/φ²  = 0.382      # Dissipation, self-damping, convergence threshold
INV_PHI3 = 1/φ³  = 0.236      # Cross-coupling, confidence floor
PHI2     = φ²    = 2.618      # Identity anchoring (κ)

Model parameters: TAU_DEFAULT = φ, KAPPA_DEFAULT = φ², DT_DEFAULT = 1/φ, ALPHA_DEFAULT = 1/φ², BETA_DEFAULT = 1/φ³

Identity profile (Ψ₀) — Luna v5.3 single-agent:

Agent	Perception	Réflexion	Intégration	Expression	Dominant
LUNA	0.260	0.322	0.250	0.168	Réflexion

External agent profiles (SAYOHMY, SENTINEL, TESTENGINEER) are defined in constants.py — each is an independent project with its own dominant faculty.

Phase thresholds: BROKEN (0.0), FRAGILE (0.25), FUNCTIONAL (0.50), SOLID (0.75), EXCELLENT (0.90) with hysteresis band ± 0.025

Consciousness Module

File	Role
simplex.py	Softmax projection onto Δ³ (τ = φ), NaN/Inf fallback
matrices.py	Γᵗ (temporal), Γˣ (spatial), Γᶜ (info) consciousness matrices
evolution.py	One step of the consciousness equation of state
context.py	Builds informational gradient ∂ᶜ from 7 cognitive metrics
profiles.py	Returns Ψ₀ for any agent by name
illusion.py	Self-illusion detection (Φ vs reality)

The equation of state:

iΓᵗ ∂ₜ + iΓˣ ∂ₓ + iΓᶜ ∂ᶜ − Φ·M·Ψ + κ·(Ψ₀ − Ψ) = 0

This equation is used at two levels in Luna v5.3+:

• MACRO: Ψ evolves between messages (dt = 1/φ)
• MICRO: Thought evolves within the Thinker (dt = 1/φ, convergence < 1/φ²)

Φ Engine

File	Role
scorer.py	PhiScorer — 7 Fibonacci-weighted EMA metrics → composite score [0, 1]
convergence.py	Detects when metrics stabilize (derivative < threshold)
phase_transition.py	State machine: BROKEN → FRAGILE → FUNCTIONAL → SOLID → EXCELLENT
soft_constraint.py	Fibonacci zone boundaries for metric evaluation
veto.py	Rule-based veto system with severity, resolution, and evidence

Schemas

Pydantic models for data exchange:

Pipeline schemas (pipeline.py)

Schema	Description
PsiState	4-component state on Δ³
InfoGradient	4-component informational gradient
CurrentTask	Task descriptor with scope and metadata
IntegrationCheck	Integration validation result
Decision	Luna's final decision (intent, depth, info_deltas)

Metrics schemas (metrics.py)

Schema	Description
NormalizedMetricsReport	7 normalized metrics
VerdictInput	Input for verdict computation

Signal schemas (signals.py)

Schema	Description
SleepNotification	Dream cycle trigger
KillSignal	Emergency shutdown
VitalsRequest / VitalsReport	Health check protocol
AuditEntry	Audit trail record

Cycle schemas (cycle.py) — v5.3

The unit of lived experience. One complete sensorimotor cycle: state → decision → action → consequences → evaluation → learning.

Schema	Description
CycleRecord	Complete cycle with ~35 fields: Ψ, Φ, thinker, decision, telemetry, voice, reward, autonomy, ghost
RewardVector	9 components across 6 dominance priority groups + δJ tie-break
RewardComponent	One dimension of the reward (name, value, raw)
TelemetrySummary	Digested pipeline signals (latency, veto rate, scope ratio, test pass rate)
TelemetryEvent	Single instrumentation event with type validation
VoiceDelta	VoiceValidator output: violations, categories, severity, modification ratio

Dominance priority groups (v5.0 — 9 cognitive components):

Priority	Components	Pillar
1	constitution_integrity, anti_collapse	Safety
2	integration_coherence, identity_stability	Intégration (ψ₃)
3	reflection_depth	Réflexion (ψ₂)
4	perception_acuity	Perception (ψ₁)
5	expression_fidelity	Expression (ψ₄)
6	affect_regulation, memory_vitality	Transversal

CycleRecord ghost fields (Phase A): auto_apply_candidate, ghost_reason, ghost_expected_rank, ghost_planned_scope

CycleRecord autonomy fields (Phase B): auto_applied, auto_rolled_back, auto_post_tests, auto_diff_stats, auto_delta_rank

Installation

cd ~/luna_common
pip install -e .

Must be installed before Luna or any agent repository.

Dependencies: pydantic>=2.0, numpy>=1.24

Usage

from luna_common.constants import PHI, INV_PHI, INV_PHI2, INV_PHI3
from luna_common.constants import AGENT_PROFILES, COMP_NAMES, METRIC_NAMES
from luna_common.consciousness import project_simplex, evolution_step, get_psi0
from luna_common.phi_engine import PhiScorer, PhaseTransitionMachine
from luna_common.schemas import PsiState, InfoGradient, Decision
from luna_common.schemas.cycle import CycleRecord, RewardVector, TelemetrySummary

Versioning Rule

NEVER modify luna_common in parallel with agents.

Sequence: luna_common tagged → agents updated one by one → integration tests.

The version tracks Luna's main version (currently 5.3) since luna_common is the shared foundation that evolves in lockstep with the orchestrator.

---

Part of the Luna Ecosystem | License: CC BY-NC 4.0