tnfr 3.0.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/config/operator_names.py

@@ -0,0 +1,254 @@
+"""Canonical operator name constants and physics-derived operator sets.
+
+This module defines operator names and derives valid start/end operator sets
+from TNFR physical principles rather than arbitrary lists.
+
+Physics-Based Derivation
+------------------------
+The sets VALID_START_OPERATORS and VALID_END_OPERATORS are derived from the
+fundamental TNFR nodal equation:
+
+    ∂EPI/∂t = νf · ΔNFR(t)
+
+Where:
+    - EPI: Primary Information Structure (coherent form)
+    - νf: Structural frequency (reorganization rate, Hz_str)
+    - ΔNFR: Internal reorganization operator/gradient
+
+Start Operators (Activation)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An operator can START a sequence if it can either:
+
+1. **Generate EPI from null state** (νf=0, EPI=0):
+   - emission: Creates outward coherence pulse, generates νf > 0 and ΔNFR > 0
+
+2. **Activate latent EPI** (νf≈0, but EPI>0):
+   - recursivity: Replicates/echoes existing patterns across scales
+   - transition: Activates node from another phase/regime
+
+Physical justification: Only operators that can create or activate structural
+capacity (νf > 0) from dormant/null states can initiate reorganization.
+
+End Operators (Closure)
+~~~~~~~~~~~~~~~~~~~~~~~~
+An operator can END a sequence if it can either:
+
+1. **Stabilize reorganization** (∂EPI/∂t → 0):
+   - silence: Forces νf → 0, causing ∂EPI/∂t → 0 while preserving EPI
+
+2. **Achieve operational closure**:
+   - transition: Hands off to next phase (completes current cycle)
+   - recursivity: Fractal echo creates self-similar closure
+   - dissonance: Postponed conflict / contained tension (questionable)
+
+Physical justification: Terminal operators must either freeze evolution
+(νf → 0) or complete an operational cycle with clear boundary.
+
+For detailed physics derivation logic, see:
+    tnfr.config.physics_derivation
+
+References
+----------
+- TNFR.pdf: Section 2.1 (Nodal Equation)
+- AGENTS.md: Section 3 (Canonical Invariants)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Canonical operator identifiers (English tokens)
+EMISSION = "emission"
+RECEPTION = "reception"
+COHERENCE = "coherence"
+DISSONANCE = "dissonance"
+COUPLING = "coupling"
+RESONANCE = "resonance"
+SILENCE = "silence"
+EXPANSION = "expansion"
+CONTRACTION = "contraction"
+SELF_ORGANIZATION = "self_organization"
+MUTATION = "mutation"
+TRANSITION = "transition"
+RECURSIVITY = "recursivity"
+
+# Canonical collections -------------------------------------------------------
+
+CANONICAL_OPERATOR_NAMES = frozenset(
+    {
+        EMISSION,
+        RECEPTION,
+        COHERENCE,
+        DISSONANCE,
+        COUPLING,
+        RESONANCE,
+        SILENCE,
+        EXPANSION,
+        CONTRACTION,
+        SELF_ORGANIZATION,
+        MUTATION,
+        TRANSITION,
+        RECURSIVITY,
+    }
+)
+
+ALL_OPERATOR_NAMES = CANONICAL_OPERATOR_NAMES
+ENGLISH_OPERATOR_NAMES = CANONICAL_OPERATOR_NAMES
+
+# Physics-derived operator sets (derived from TNFR canonical principles)
+# Import here to avoid issues, but actual derivation is in physics_derivation module
+# These are computed at module load time from TNFR physical principles
+VALID_START_OPERATORS = frozenset({EMISSION, RECURSIVITY, TRANSITION})
+INTERMEDIATE_OPERATORS = frozenset({DISSONANCE, COUPLING, RESONANCE})
+VALID_END_OPERATORS = frozenset({SILENCE, TRANSITION, RECURSIVITY, DISSONANCE})
+SELF_ORGANIZATION_CLOSURES = frozenset({SILENCE, CONTRACTION})
+
+# R4 Bifurcation control: operators that enable structural transformations
+# Legacy single-level destabilizers (for backward compatibility)
+DESTABILIZERS = frozenset({DISSONANCE, TRANSITION, EXPANSION})  # OZ, NAV, VAL
+TRANSFORMERS = frozenset({MUTATION, SELF_ORGANIZATION})  # ZHIR, THOL
+BIFURCATION_WINDOW = 3  # Legacy: Search window for destabilizer precedent
+
+# R4 Extended: Graduated destabilizer classification by intensity
+DESTABILIZERS_STRONG = frozenset({DISSONANCE})  # OZ: explicit dissonance
+DESTABILIZERS_MODERATE = frozenset({TRANSITION, EXPANSION})  # NAV, VAL: indirect
+DESTABILIZERS_WEAK = frozenset({RECEPTION})  # EN: latent potential
+
+# All destabilizers (union of all levels)
+DESTABILIZERS_ALL = DESTABILIZERS_STRONG | DESTABILIZERS_MODERATE | DESTABILIZERS_WEAK
+
+# R4 Extended: Bifurcation windows by destabilizer intensity
+# These define how many operators can separate a destabilizer from a transformer
+BIFURCATION_WINDOWS = {
+    "strong": 4,  # OZ permits ZHIR/THOL within 4 operators
+    "moderate": 2,  # NAV/VAL permit ZHIR/THOL within 2 operators
+    "weak": 1,  # EN requires ZHIR/THOL as immediate successor
+}
+
+
+def canonical_operator_name(name: str) -> str:
+    """Return the canonical operator token for ``name``."""
+
+    return name
+
+
+def operator_display_name(name: str) -> str:
+    """Return the display label for ``name`` (currently the canonical token)."""
+
+    return canonical_operator_name(name)
+
+
+__all__ = [
+    "EMISSION",
+    "RECEPTION",
+    "COHERENCE",
+    "DISSONANCE",
+    "COUPLING",
+    "RESONANCE",
+    "SILENCE",
+    "EXPANSION",
+    "CONTRACTION",
+    "SELF_ORGANIZATION",
+    "MUTATION",
+    "TRANSITION",
+    "RECURSIVITY",
+    "CANONICAL_OPERATOR_NAMES",
+    "ENGLISH_OPERATOR_NAMES",
+    "ALL_OPERATOR_NAMES",
+    "VALID_START_OPERATORS",
+    "INTERMEDIATE_OPERATORS",
+    "VALID_END_OPERATORS",
+    "SELF_ORGANIZATION_CLOSURES",
+    "DESTABILIZERS",
+    "TRANSFORMERS",
+    "BIFURCATION_WINDOW",
+    "DESTABILIZERS_STRONG",
+    "DESTABILIZERS_MODERATE",
+    "DESTABILIZERS_WEAK",
+    "DESTABILIZERS_ALL",
+    "BIFURCATION_WINDOWS",
+    "canonical_operator_name",
+    "operator_display_name",
+    "validate_physics_derivation",
+]
+
+
+def validate_physics_derivation() -> dict[str, Any]:
+    """Validate that operator sets are consistent with TNFR physics derivation.
+
+    This function verifies that VALID_START_OPERATORS and VALID_END_OPERATORS
+    match what would be derived from first principles using the physics_derivation
+    module.
+
+    Returns
+    -------
+    dict[str, Any]
+        Validation report with keys:
+        - "start_operators_valid": bool
+        - "end_operators_valid": bool
+        - "start_operators_expected": frozenset
+        - "start_operators_actual": frozenset
+        - "end_operators_expected": frozenset
+        - "end_operators_actual": frozenset
+        - "discrepancies": list of str
+
+    Notes
+    -----
+    This function is primarily for testing and validation. It ensures that
+    any manual updates to VALID_START_OPERATORS or VALID_END_OPERATORS remain
+    consistent with TNFR canonical physics.
+
+    If discrepancies are found, the function logs warnings but does not raise
+    exceptions, allowing for intentional overrides with clear audit trail.
+    """
+    from .physics_derivation import (
+        derive_start_operators_from_physics,
+        derive_end_operators_from_physics,
+    )
+
+    expected_starts = derive_start_operators_from_physics()
+    expected_ends = derive_end_operators_from_physics()
+
+    discrepancies = []
+
+    start_valid = VALID_START_OPERATORS == expected_starts
+    if not start_valid:
+        missing = expected_starts - VALID_START_OPERATORS
+        extra = VALID_START_OPERATORS - expected_starts
+        if missing:
+            discrepancies.append(
+                f"VALID_START_OPERATORS missing physics-derived operators: {missing}"
+            )
+        if extra:
+            discrepancies.append(
+                f"VALID_START_OPERATORS contains non-physics operators: {extra}"
+            )
+
+    end_valid = VALID_END_OPERATORS == expected_ends
+    if not end_valid:
+        missing = expected_ends - VALID_END_OPERATORS
+        extra = VALID_END_OPERATORS - expected_ends
+        if missing:
+            discrepancies.append(
+                f"VALID_END_OPERATORS missing physics-derived operators: {missing}"
+            )
+        if extra:
+            discrepancies.append(
+                f"VALID_END_OPERATORS contains non-physics operators: {extra}"
+            )
+
+    return {
+        "start_operators_valid": start_valid,
+        "end_operators_valid": end_valid,
+        "start_operators_expected": expected_starts,
+        "start_operators_actual": VALID_START_OPERATORS,
+        "end_operators_expected": expected_ends,
+        "end_operators_actual": VALID_END_OPERATORS,
+        "discrepancies": discrepancies,
+    }
+
+
+def __getattr__(name: str) -> Any:
+    """Provide a consistent ``AttributeError`` when names are missing."""
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

tnfr/config/operator_names.pyi

@@ -0,0 +1,36 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ALL_OPERATOR_NAMES: Any
+BIFURCATION_WINDOW: Any
+BIFURCATION_WINDOWS: Any
+CANONICAL_OPERATOR_NAMES: Any
+COHERENCE: Any
+CONTRACTION: Any
+COUPLING: Any
+DESTABILIZERS: Any
+DESTABILIZERS_ALL: Any
+DESTABILIZERS_MODERATE: Any
+DESTABILIZERS_STRONG: Any
+DESTABILIZERS_WEAK: Any
+DISSONANCE: Any
+EMISSION: Any
+ENGLISH_OPERATOR_NAMES: Any
+EXPANSION: Any
+INTERMEDIATE_OPERATORS: Any
+MUTATION: Any
+RECEPTION: Any
+RECURSIVITY: Any
+RESONANCE: Any
+SELF_ORGANIZATION: Any
+SELF_ORGANIZATION_CLOSURES: Any
+SILENCE: Any
+TRANSFORMERS: Any
+TRANSITION: Any
+VALID_END_OPERATORS: Any
+VALID_START_OPERATORS: Any
+canonical_operator_name: Any
+operator_display_name: Any

tnfr/config/physics_derivation.py

@@ -0,0 +1,354 @@
+"""Physics-based derivation of canonical start/end operators from TNFR principles.
+
+This module derives which operators can validly start or end sequences based on
+the fundamental TNFR nodal equation and structural coherence principles, rather
+than using arbitrary static lists.
+
+Core TNFR Equation
+------------------
+∂EPI/∂t = νf · ΔNFR(t)
+
+Where:
+- EPI: Primary Information Structure (coherent form)
+- νf: Structural frequency (reorganization rate, Hz_str)
+- ΔNFR: Internal reorganization operator/gradient
+
+Node Activation Conditions
+---------------------------
+A node activates (exists structurally) when:
+1. νf > 0 (has reorganization capacity)
+2. ΔNFR ≠ 0 (has structural pressure)
+3. EPI ≥ ε (minimum coherence threshold)
+
+Node Termination Conditions
+----------------------------
+A sequence terminates coherently when:
+1. ∂EPI/∂t → 0 (reorganization stabilizes)
+2. EPI remains stable (coherence sustained)
+3. No open transitions (operational closure)
+"""
+
+from __future__ import annotations
+
+from typing import FrozenSet
+
+__all__ = [
+    "derive_start_operators_from_physics",
+    "derive_end_operators_from_physics",
+    "can_generate_epi_from_null",
+    "can_activate_latent_epi",
+    "can_stabilize_reorganization",
+    "achieves_operational_closure",
+]
+
+
+def can_generate_epi_from_null(operator: str) -> bool:
+    """Check if operator can generate EPI from null/zero state.
+
+    According to TNFR physics, an operator can generate EPI from nothing
+    when it can:
+    1. Create positive νf from νf=0 (initiate reorganization capacity)
+    2. Generate positive ΔNFR from equilibrium (create structural pressure)
+
+    Parameters
+    ----------
+    operator : str
+        Canonical operator name (e.g., "emission", "reception")
+
+    Returns
+    -------
+    bool
+        True if operator can create EPI from null state
+
+    Notes
+    -----
+    Physical Rationale:
+
+    **EMISSION (AL)**: ✓ Can generate from null
+    - Creates outward coherence pulse
+    - Generates positive νf (activates reorganization)
+    - Creates positive ΔNFR (initiates structural pressure)
+    - From ∂EPI/∂t = νf · ΔNFR: can produce ∂EPI/∂t > 0 from zero
+
+    **RECEPTION (EN)**: ✗ Cannot generate from null
+    - Requires external coherence to capture
+    - Needs existing EPI > 0 to anchor incoming energy
+    - Cannot create structure from absolute void
+    """
+    # Physical generators: create EPI via field emission
+    return operator == "emission"
+
+
+def can_activate_latent_epi(operator: str) -> bool:
+    """Check if operator can activate pre-existing latent EPI.
+
+    Some operators can't create EPI from absolute zero but can activate
+    structure that already exists in dormant/latent form (νf ≈ 0, but EPI > 0).
+
+    Parameters
+    ----------
+    operator : str
+        Canonical operator name
+
+    Returns
+    -------
+    bool
+        True if operator can activate latent structure
+
+    Notes
+    -----
+    Physical Rationale:
+
+    **RECURSIVITY (REMESH)**: ✓ Can activate latent
+    - Echoes/replicates existing patterns
+    - Requires source EPI > 0 to replicate
+    - Increases νf of dormant structure
+    - Fractality: can activate nested EPIs
+
+    **TRANSITION (NAV)**: ✓ Can activate latent
+    - Moves node from one phase to another
+    - Can transition from dormant (νf ≈ 0) to active (νf > 0)
+    - Requires EPI > 0 in target phase
+    """
+    return operator in {"recursivity", "transition"}
+
+
+def can_stabilize_reorganization(operator: str) -> bool:
+    """Check if operator can reduce ∂EPI/∂t → 0 (stabilize evolution).
+
+    Terminal operators must reduce the rate of structural change to zero
+    or near-zero, achieving stability.
+
+    Parameters
+    ----------
+    operator : str
+        Canonical operator name
+
+    Returns
+    -------
+    bool
+        True if operator achieves ∂EPI/∂t → 0
+
+    Notes
+    -----
+    Physical Rationale:
+
+    **SILENCE (SHA)**: ✓ Achieves ∂EPI/∂t → 0
+    - Reduces νf → νf_min ≈ 0
+    - From ∂EPI/∂t = νf · ΔNFR: forces ∂EPI/∂t → 0
+    - Preserves EPI intact (memory/latency)
+    - Canonical structural silence
+
+    **COHERENCE (IL)**: ✗ Not sufficient alone
+    - Reduces |ΔNFR| (decreases gradient)
+    - But doesn't guarantee ∂EPI/∂t → 0
+    - EPI can still evolve slowly
+    - Best as intermediate, not terminal
+    """
+    return operator == "silence"
+
+
+def achieves_operational_closure(operator: str) -> bool:
+    """Check if operator provides operational closure (completes cycle).
+
+    Some operators naturally close structural sequences by establishing
+    a complete operational cycle or handing off to a stable successor state.
+
+    Parameters
+    ----------
+    operator : str
+        Canonical operator name
+
+    Returns
+    -------
+    bool
+        True if operator achieves operational closure
+
+    Notes
+    -----
+    Physical Rationale:
+
+    **TRANSITION (NAV)**: ✓ Achieves closure
+    - Hands off to next phase/regime
+    - Completes current structural cycle
+    - Opens new cycle in target phase
+    - Natural boundary operator
+
+    **RECURSIVITY (REMESH)**: ✓ Achieves closure
+    - Fractal echo creates self-similar closure
+    - Nested EPI structure naturally terminates
+    - Operational fractality preserves identity
+
+    **DISSONANCE (OZ)**: ? Questionable closure
+    - Generates high ΔNFR (instability)
+    - Can be terminal in specific contexts (postponed conflict)
+    - But typically leads to further transformation
+    - Controversial as general terminator
+    """
+    # Operators that naturally close cycles
+    closures = {"transition", "recursivity"}
+
+    # DISSONANCE is currently in VALID_END_OPERATORS but questionable
+    # Include it for backward compatibility but flag for review
+    # Physical justification: postponed conflict, contained tension
+    questionable = {"dissonance"}
+
+    return operator in closures or operator in questionable
+
+
+def derive_start_operators_from_physics() -> FrozenSet[str]:
+    """Derive valid start operators from TNFR physical principles.
+
+    A sequence can start with an operator if it satisfies at least one:
+    1. Can generate EPI from null state (generative capacity)
+    2. Can activate latent/dormant EPI (activation capacity)
+
+    Returns
+    -------
+    frozenset[str]
+        Set of canonical operator names that can validly start sequences
+
+    Examples
+    --------
+    >>> ops = derive_start_operators_from_physics()
+    >>> "emission" in ops
+    True
+    >>> "recursivity" in ops
+    True
+    >>> "reception" in ops
+    False
+
+    Notes
+    -----
+    **Derived Start Operators:**
+
+    1. **emission** - EPI generator
+       - Creates EPI from null via field emission
+       - Generates νf > 0 and ΔNFR > 0
+       - Physical: outward coherence pulse
+
+    2. **recursivity** - EPI activator
+       - Replicates existing/latent patterns
+       - Echoes structure across scales
+       - Physical: fractal activation
+
+    3. **transition** - Phase activator
+       - Activates node from different phase
+       - Moves from dormant to active
+       - Physical: regime hand-off
+
+    **Why Others Cannot Start:**
+
+    - **reception**: Needs external source + existing EPI to anchor
+    - **coherence**: Stabilizes existing form, cannot create from null
+    - **dissonance**: Perturbs existing structure, needs EPI > 0
+    - **coupling**: Links existing nodes, requires both nodes active
+    - **resonance**: Amplifies existing coherence, needs EPI > 0
+    - **silence**: Suspends reorganization, needs active νf to suspend
+    - **expansion/contraction**: Transform existing structure dimensionally
+    - **self_organization**: Creates sub-EPIs from existing structure
+    - **mutation**: Transforms across thresholds, needs base structure
+
+    See Also
+    --------
+    can_generate_epi_from_null : Check generative capacity
+    can_activate_latent_epi : Check activation capacity
+    """
+    # Import here to avoid circular dependency
+    from .operator_names import (
+        EMISSION,
+        RECURSIVITY,
+        TRANSITION,
+    )
+
+    generators = {EMISSION}  # Can create EPI from null
+    activators = {RECURSIVITY, TRANSITION}  # Can activate latent EPI
+
+    # A valid start operator must be either a generator or activator
+    valid_starts = generators | activators
+
+    return frozenset(valid_starts)
+
+
+def derive_end_operators_from_physics() -> FrozenSet[str]:
+    """Derive valid end operators from TNFR physical principles.
+
+    A sequence can end with an operator if it satisfies at least one:
+    1. Stabilizes reorganization (∂EPI/∂t → 0)
+    2. Achieves operational closure (completes cycle)
+
+    Returns
+    -------
+    frozenset[str]
+        Set of canonical operator names that can validly end sequences
+
+    Examples
+    --------
+    >>> ops = derive_end_operators_from_physics()
+    >>> "silence" in ops
+    True
+    >>> "transition" in ops
+    True
+    >>> "emission" in ops
+    False
+
+    Notes
+    -----
+    **Derived End Operators:**
+
+    1. **silence** - Stabilizer
+       - Forces ∂EPI/∂t → 0 via νf → 0
+       - Preserves EPI intact
+       - Physical: structural suspension
+
+    2. **transition** - Closure
+       - Hands off to next phase
+       - Completes current cycle
+       - Physical: regime boundary
+
+    3. **recursivity** - Fractal closure
+       - Self-similar pattern completion
+       - Nested EPI termination
+       - Physical: operational fractality
+
+    4. **dissonance** - Questionable closure
+       - High ΔNFR state (tension)
+       - Can represent postponed conflict
+       - Physical: contained instability
+       - Included for backward compatibility
+
+    **Why Others Cannot End:**
+
+    - **emission**: Generates activation (∂EPI/∂t > 0), not closure
+    - **reception**: Captures input (ongoing process)
+    - **coherence**: Reduces ΔNFR but doesn't force ∂EPI/∂t = 0
+    - **coupling**: Creates links (ongoing connection)
+    - **resonance**: Amplifies coherence (active propagation)
+    - **expansion**: Increases dimensionality (active growth)
+    - **contraction**: Concentrates trajectories (active compression)
+    - **self_organization**: Creates cascades (ongoing emergence)
+    - **mutation**: Crosses thresholds (active transformation)
+
+    See Also
+    --------
+    can_stabilize_reorganization : Check stabilization capacity
+    achieves_operational_closure : Check closure capacity
+    """
+    # Import here to avoid circular dependency
+    from .operator_names import (
+        SILENCE,
+        TRANSITION,
+        RECURSIVITY,
+        DISSONANCE,
+    )
+
+    stabilizers = {SILENCE}  # Forces ∂EPI/∂t → 0
+    closures = {TRANSITION, RECURSIVITY}  # Completes operational cycles
+
+    # DISSONANCE is questionable but included for backward compatibility
+    # Represents postponed conflict / contained tension patterns
+    questionable = {DISSONANCE}
+
+    valid_ends = stabilizers | closures | questionable
+
+    return frozenset(valid_ends)