feat: update version to 1.4.1 and enhance functionality with SigmaGuard integration, improved compatibility checks, and expanded documentation

Author: r4dm

.gitignore

@@ -15,3 +15,4 @@ FULL.md
 dist/
 build/
 docs/
+.github/

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.4.1 — 2026-03-13
+
+- Hardened antenna and receiver compatibility checks: pole-count validation, loka/polarity metadata matching, and keyed frequency gating now live directly in the device pipeline.
+- Integrated `SigmaGuard` into receiver-side purification flows and aligned `secure_transmission` / `property_transfer_chain` with the explicit O2 cleanup path.
+- Expanded theory-facing coverage for odd-N cascades, translation-gap branches, `probability_tensor()`, and clean-state witness/noise validation.
+- Reworded tetradic/pseudo-quantum helper metadata so complex arithmetic, phase operators, and direct composition are clearly marked as projection/reference vocabulary rather than primary multipolar law.
+
 ## 1.4.0 — 2026-02-05
 
 - Added weighted linear Σ (Σ_c = ∑(cᵢ·aᵢ)) support via `linear_coeffs` in `physics/sigma.py` and `physics/pseudomultipolar_timeseries.py`.

applications/scenarios.py

@@ -58,15 +58,16 @@ def object_polarity_scan(params: Dict[str, Any]) -> None:
 def secure_transmission(params: Dict[str, Any]) -> None:
     key = DynamicKey(polarities=[3, 4, 5, 6], freqs_hz=[110.0, 130.0, 150.0, 170.0])
     tx = MultipolarTransmitter(MultipolarOscillator([_default_inductor()], [_default_capacitor()]), key=key)
+    guard = SigmaGuard(sections=2)
     rx = MultipolarReceiver(
         MultipolarOscillator([_default_inductor()], [_default_capacitor()]),
         key=DynamicKey(polarities=[3, 4, 5, 6], freqs_hz=[110.0, 130.0, 150.0, 170.0]),
+        sigma_guard=guard,
     )
     tx_antennas: Dict[int, MultipolarAntenna] = {}
     rx_antennas: Dict[int, MultipolarAntenna] = {}
     messages = list(params.get("messages", [1, 0, 2, 3, 1, 3]))
     good: List[int] = []
-    guard = SigmaGuard(sections=2)
     for msg in messages:
         wave = tx.transmit([msg])
         n = wave.n_conjugates
@@ -75,24 +76,7 @@ def secure_transmission(params: Dict[str, Any]) -> None:
         emitted = tx_ant.emit(wave)
         received = rx_ant.receive(emitted)
         if rx.receive(received):
-            # Apply SigmaGuard (NX) before decoding to enforce Σ→0
-            mv = received.to_multipolar_value(rx.loka)
-            purified = guard.apply_nx(mv, sections=guard.sections)[-1]
-            purified_vec = np.asarray(
-                [purified.coefficients.get(p, 0.0) for p in purified.loka.polarities],
-                dtype=np.complex128,
-            )
-            purified_wave = MultiConjugateFunction(
-                purified,
-                n_conjugates=received.n_conjugates,
-                metadata=WaveMetadata.from_amplitudes(
-                    purified_vec,
-                    loka_name=purified.loka.name,
-                    polarity_names=[p.name for p in purified.loka.polarities],
-                    frequency_hz=(received.metadata.frequency_hz if received.metadata else None),
-                ),
-            )
-            good.extend(rx.demodulate(purified_wave))
+            good.extend(rx.demodulate())
     outdir = _outdir(params, "runs/secure_transmission")
     (outdir / "result.json").write_text(json.dumps({"sent": messages, "received": good}, indent=2))
 
@@ -123,12 +107,16 @@ def property_transfer_chain(params: Dict[str, Any]) -> None:
     tx_osc = MultipolarOscillator([_default_inductor()], [_default_capacitor()], mind=mind)
     rx_osc = MultipolarOscillator([_default_inductor()], [_default_capacitor()], mind=mind)
     tx = MultipolarTransmitter(tx_osc, mind=mind)
-    rx = MultipolarReceiver(rx_osc, mind=mind)
+    rx = MultipolarReceiver(rx_osc, mind=mind, sigma_guard=SigmaGuard())
+    tx_ant = MultipolarAntenna(polarity=tx.rank, role="tx")
+    rx_ant = MultipolarAntenna(polarity=rx.rank, role="rx")
     decoded: List[int] = []
     for msg in messages:
         wave = tx.transmit([msg])
-        rx.receive(wave)
-        decoded.extend(rx.demodulate())
+        emitted = tx_ant.emit(wave)
+        received = rx_ant.receive(emitted)
+        if rx.receive(received):
+            decoded.extend(rx.demodulate())
     outdir = _outdir(params, "runs/property_transfer")
     (outdir / "messages.json").write_text(json.dumps({"sent": messages, "decoded": decoded}, indent=2))
 
@@ -359,6 +347,15 @@ def pseudo_quantum_witness_pack(params: Dict[str, Any]) -> None:
     else:
         psi = psi / norm
     sigma_in = complex(psi.sum())
+    psi = psi - (sigma_in / float(dim))
+    clean_norm = float(np.linalg.norm(psi))
+    if clean_norm == 0.0:
+        psi = (np.ones(dim, dtype=np.complex128) + 0.0j) / np.sqrt(dim)
+        psi = psi - complex(psi.sum()) / float(dim)
+        clean_norm = float(np.linalg.norm(psi))
+    psi = psi / clean_norm
+    sigma_after_clean = complex(psi.sum())
+    clean_state = bool(abs(sigma_after_clean) < 1e-10)
 
     rng_consistent = np.random.default_rng(None if seed is None else seed + 1)
     rng_generic = np.random.default_rng(None if seed is None else seed + 2)
@@ -380,10 +377,12 @@ def pseudo_quantum_witness_pack(params: Dict[str, Any]) -> None:
                 "sigma_noise": {
                     "dim": dim,
                     "sigma_in": [float(sigma_in.real), float(sigma_in.imag)],
+                    "sigma_after_clean": [float(sigma_after_clean.real), float(sigma_after_clean.imag)],
+                    "clean_state": clean_state,
                     "sigma_out_sigma_consistent": [float(sigma_out_sigma.real), float(sigma_out_sigma.imag)],
                     "sigma_out_generic": [float(sigma_out_generic.real), float(sigma_out_generic.imag)],
-                    "delta_sigma_consistent": float(abs(sigma_out_sigma - sigma_in)),
-                    "delta_sigma_generic": float(abs(sigma_out_generic - sigma_in)),
+                    "delta_sigma_consistent": float(abs(sigma_out_sigma - sigma_after_clean)),
+                    "delta_sigma_generic": float(abs(sigma_out_generic - sigma_after_clean)),
                 },
             },
             indent=2,

core/algebras.py

@@ -583,11 +583,11 @@ def __init__(self, n: int, operation_type: str, loka_name: str, polarity_names:
             1: "unit_conserve",
             2: "binary_linear",
             3: "triadic_superposition",
-            4: "complex_wave",
+            4: "tetradic_projection",
             5: "quaternion_harloka",
             6: "relational_visibility",
             7: "relational_visibility",
-            8: "complex_wave",
+            8: "tetradic_projection",
             9: "quaternion_harloka",
             10: "relational_visibility",
         }

core/loka.py

@@ -63,12 +63,12 @@ class TattvaProfile:
         intensity_mode="sigma_mul",
     ),
     DharmaProfile(
-        name="complex_wave_kernel",
-        relations=("exp(i*phi)", "r^2 = ln(1 + w/eps)"),
+        name="tetradic_projection_kernel",
+        relations=("phase_projection(phi)", "amplitude_response(w, eps)"),
         polarity_arity=4,
         theory_refs=("complex_wave_behaviour",),
-        description="Four-pole complex waves mix amplitude and phase in the Sigma ladder.",
-        intensity_mode="sigma_phase",
+        description="Four-pole tetradic projections mix amplitude-like and phase-like coordinates in Sigma diagnostics.",
+        intensity_mode="sigma_tetradic",
     ),
     DharmaProfile(
         name="harloka_bundle_kernel",
@@ -190,22 +190,22 @@ def _seed_default_registries() -> None:
             intensity_modes=("sigma_mul", "sigma_add"),
         ),
         TattvaProfile(
-            name="complex_wave",
+            name="tetradic_projection",
             polarity_count=4,
-            dharmas=("complex_wave_kernel",),
+            dharmas=("tetradic_projection_kernel",),
             theory_refs=("complex_wave_behaviour",),
-            description="Four-pole complex wave base with amplitude-phase balance.",
-            mind_modes=("complex", "wave"),
-            intensity_modes=("sigma_phase", "sigma_add", "sigma_mul"),
+            description="Four-pole tetradic base for projection-aware Sigma diagnostics.",
+            mind_modes=("tetradic", "projection"),
+            intensity_modes=("sigma_tetradic", "sigma_add", "sigma_mul"),
         ),
         TattvaProfile(
             name="quaternion_harloka",
             polarity_count=4,
-            dharmas=("triadic_superposition_kernel", "complex_wave_kernel", "harloka_bundle_kernel"),
+            dharmas=("triadic_superposition_kernel", "tetradic_projection_kernel", "harloka_bundle_kernel"),
             theory_refs=("harloka_bundle",),
             description="Harloka bundle linking triadic and tetradic poles.",
             mind_modes=("harloka",),
-            intensity_modes=("sigma_mul", "sigma_phase"),
+            intensity_modes=("sigma_mul", "sigma_tetradic"),
         ),
         TattvaProfile(
             name="relational_visibility",
@@ -223,7 +223,7 @@ def _seed_default_registries() -> None:
             theory_refs=("hyper_wave_patterns",),
             description="High-rank hyper wave cascades with alternating parity.",
             mind_modes=("hyper",),
-            intensity_modes=("sigma_phase", "sigma_add", "sigma_mul", "sigma_gate"),
+            intensity_modes=("sigma_tetradic", "sigma_add", "sigma_mul", "sigma_gate"),
         ),
     )
     for tattva in tattvas:

devices/communication.py

@@ -130,20 +130,44 @@ class MultipolarAntenna:
     - role: informational label ("tx" or "rx").
     - gain: linear gain multiplier (applied after losses).
     - loss_db: additional attenuation in dB (applied symmetrically on emit/receive).
+    - strict_polarity: reject waves whose pole count does not match the tuning.
     """
 
-    def __init__(self, *, polarity: int, role: str = "tx", gain: float = 1.0, loss_db: float = 0.0) -> None:
+    def __init__(
+        self,
+        *,
+        polarity: int,
+        role: str = "tx",
+        gain: float = 1.0,
+        loss_db: float = 0.0,
+        strict_polarity: bool = True,
+    ) -> None:
         self.polarity = int(polarity)
         self.role = role
         self.gain = float(gain)
         self.loss_db = float(loss_db)
+        self.strict_polarity = bool(strict_polarity)
 
     def _scale(self) -> float:
         # Convert dB loss to linear and apply gain
         loss_lin = 10.0 ** (-self.loss_db / 20.0) if self.loss_db != 0.0 else 1.0
         return self.gain * loss_lin
 
+    def is_compatible(self, wave: MultiConjugateFunction) -> bool:
+        if wave.n_conjugates != self.polarity:
+            return False
+        if wave.metadata is None:
+            return True
+        return len(wave.metadata.polarity_names) == self.polarity
+
+    def _validate_wave(self, wave: MultiConjugateFunction) -> None:
+        if self.strict_polarity and not self.is_compatible(wave):
+            raise ValueError(
+                f"antenna tuned for {self.polarity} poles cannot handle wave with {wave.n_conjugates} poles"
+            )
+
     def emit(self, wave: MultiConjugateFunction) -> MultiConjugateFunction:
+        self._validate_wave(wave)
         scaled = wave.copy()
         scaled.amplitudes = scaled.amplitudes * self._scale()
         if scaled.metadata is not None:
@@ -156,6 +180,7 @@ def emit(self, wave: MultiConjugateFunction) -> MultiConjugateFunction:
         return scaled
 
     def receive(self, wave: MultiConjugateFunction) -> MultiConjugateFunction:
+        self._validate_wave(wave)
         scaled = wave.copy()
         scaled.amplitudes = scaled.amplitudes * self._scale()
         if scaled.metadata is not None:

devices/detectors.py

@@ -18,8 +18,9 @@
 from .media import MediaPhantom
 from .passport import CascadeStage, StructuralPassport
 from .sources import MultipolarOscillator
+from .sigma_guard import SigmaGuard
 from ..cognition.base import AbstractMind
-from ..physics.multipolar_wave import MultiConjugateFunction
+from ..physics.multipolar_wave import MultiConjugateFunction, WaveMetadata
 
 
 class MultipolarMicrophone:
@@ -121,6 +122,7 @@ def __init__(
         oscillator: MultipolarOscillator,
         *,
         key: DynamicKey | None = None,
+        sigma_guard: SigmaGuard | None = None,
         name: str | None = None,
         mind: AbstractMind | None = None,
         loka: Loka | str | None = None,
@@ -130,6 +132,7 @@ def __init__(
         super().__init__(mind=mind, loka=loka, default_rank=desired_rank)
         self.oscillator = oscillator
         self.key = key
+        self.sigma_guard = sigma_guard
         self.name = name or "MultipolarReceiver"
         if self.oscillator.get_polarity() != self.rank:
             self.oscillator.set_polarity(self.rank)
@@ -157,6 +160,8 @@ def _build_passport(self) -> StructuralPassport:
         notes = ["Receiver mirrors the transmitter's Sigma guard to close the cascade."]
         if self.key is not None:
             notes.append("Dynamic key retunes polarity and frequency before each capture.")
+        if self.sigma_guard is not None:
+            notes.append("SigmaGuard purification is active before decoding.")
         return StructuralPassport(
             device_name=self.name,
             cascade=cascade,
@@ -182,44 +187,104 @@ def set_polarity(self, n_poles: int) -> None:
         self._coder = PolarCoder(self._n_polarities, loka=self.loka)
         self._sync_passport()
 
-    def is_compatible(self, wave: MultiConjugateFunction, *, tol_poles: int = 0, tol_freq: float | None = None) -> bool:
+    def _expected_loka_names(self) -> set[str]:
+        return {self.loka.name, self.oscillator.loka.name}
+
+    def _expected_polarity_names(self) -> list[str]:
+        return [p.name for p in self.loka.polarities]
+
+    def _metadata_is_compatible(self, wave: MultiConjugateFunction) -> bool:
+        meta = wave.metadata
+        if meta is None:
+            return True
+        if meta.loka_name not in self._expected_loka_names():
+            return False
+        if len(meta.polarity_names) != self.rank:
+            return False
+        return list(meta.polarity_names) == self._expected_polarity_names()
+
+    def _purify_wave(self, wave: MultiConjugateFunction) -> MultiConjugateFunction:
+        if self.sigma_guard is None:
+            return wave.copy()
+        mv = wave.to_multipolar_value(self.loka)
+        purified = self.sigma_guard.apply_nx(mv, sections=self.sigma_guard.sections)[-1]
+        amplitudes = np.asarray(
+            [purified.coefficients.get(p, 0.0) for p in purified.loka.polarities],
+            dtype=np.complex128,
+        )
+        frequency_hz = self.oscillator.working_frequency
+        if wave.metadata is not None and wave.metadata.frequency_hz is not None:
+            frequency_hz = wave.metadata.frequency_hz
+        metadata = WaveMetadata.from_amplitudes(
+            amplitudes,
+            loka_name=purified.loka.name,
+            polarity_names=[p.name for p in purified.loka.polarities],
+            frequency_hz=frequency_hz,
+        )
+        return MultiConjugateFunction(amplitudes, n_conjugates=self.rank, metadata=metadata)
+
+    def is_compatible(
+        self,
+        wave: MultiConjugateFunction,
+        *,
+        tol_poles: int = 0,
+        tol_freq: float | None = None,
+        require_frequency: bool = False,
+    ) -> bool:
         poles_ok = abs(wave.n_conjugates - self.rank) <= tol_poles
         if not poles_ok:
             return False
+        if not self._metadata_is_compatible(wave):
+            return False
         # Frequency check: only compare against explicit frequency metadata if requested
-        if tol_freq is None or wave.metadata is None:
+        if tol_freq is None:
             return poles_ok
+        if wave.metadata is None:
+            return False if require_frequency else poles_ok
         freq_meta = wave.metadata.frequency_hz
         if freq_meta is None:
-            return poles_ok
+            return False if require_frequency else poles_ok
         return abs(freq_meta - self.oscillator.working_frequency) <= tol_freq
 
-    def receive(self, wave: MultiConjugateFunction) -> bool:
+    def receive(self, wave: MultiConjugateFunction, *, purify: bool | None = None) -> bool:
         if self.key is not None:
             n_pol, freq = self.key.next()
             self.set_polarity(n_pol)
             self.oscillator.set_frequency(freq)
             self.structural_passport.record_metric("configured_polarity", float(self.rank))
-        tol_freq = 1.0 if self.key is None else None
-        if not self.is_compatible(wave, tol_freq=tol_freq):
+            self.structural_passport.record_metric("working_frequency_hz", self.oscillator.working_frequency)
+        tol_freq = 1.0
+        if not self.is_compatible(wave, tol_freq=tol_freq, require_frequency=self.key is not None):
             return False
-        self._last_wave = wave
+        should_purify = self.sigma_guard is not None if purify is None else bool(purify)
+        self._last_wave = self._purify_wave(wave) if should_purify else wave.copy()
+        if self._last_wave.metadata is not None:
+            self.structural_passport.record_metric("last_sigma_norm", self._last_wave.metadata.sigma_norm)
         return True
 
+    def receive_and_purify(self, wave: MultiConjugateFunction) -> bool:
+        return self.receive(wave, purify=True)
+
     def last_wave(self) -> Optional[MultiConjugateFunction]:
         return self._last_wave
 
-    def demodulate(self, wave: Optional[MultiConjugateFunction] = None) -> List[int]:
+    def demodulate(self, wave: Optional[MultiConjugateFunction] = None, *, purify: bool | None = None) -> List[int]:
         target = wave or self._last_wave
         if target is None:
             return []
+        should_purify = self.sigma_guard is not None if purify is None else bool(purify)
+        if should_purify:
+            target = self._purify_wave(target)
         amps = target.amplitudes
         if amps.size == 0:
             return []
         idx = int(np.argmax(np.abs(amps)))
         self.structural_passport.record_metric("last_demodulated", float(idx))
         return [idx]
 
+    def demodulate_clean(self, wave: Optional[MultiConjugateFunction] = None) -> List[int]:
+        return self.demodulate(wave, purify=True)
+
     def describe_structure(self) -> dict:
         self._sync_passport()
         return self.structural_passport.to_dict()

physics/composition.py

@@ -8,6 +8,8 @@
 Note: this is a *direct-sum style* wiring (no shared neutral between layers).
 For superposition spaces that require a common neutral, keep
 ``require_shared_neutral=True`` when constructing :class:`SuperpositionalLoka`.
+This helper is algebra-only wiring and is not a substitute for the physical
+formation/removal cascade used in M/N device flows.
 """
 
 from __future__ import annotations