THE KEY EMERGES
A Constructive Inference Demo From Survival to Structure
core_types.py Shared data structures
All modules import from here. These types define the interfaces
between stages. Changing a type here is a breaking change do it
deliberately and propagate the change.
No logic lives here. No GIE assumptions are encoded here beyond
the structural separation of: raw signal, survived structure,
composed object, world result.
from **future** import annotations
from dataclasses import dataclass, field
from enum import Enum, auto
from typing import Any, Dict, List, Optional, Tuple
import numpy as np
#
# Enumerations
#
class ArmID(Enum):
ARM_1 = auto()
ARM_2 = auto()
class FailureMode(Enum):
World constraint failure modes.
These are constraint violations, not recognition failures.
The world does not check answers it enforces rules.
NONE = auto()
CANNOT_INSERT = auto() # geometry incompatible with aperture
INSERTS_BUT_JAMS = auto() # enters but fails rotation test
ROTATES_BUT_NO_TRIGGER = auto() # rotation completes, activation fails
INADMISSIBLE = auto() # hard veto structurally invalid before world test
class StageLabel(Enum):
SIGNAL_GENERATION = auto()
LENS_SEARCH = auto()
SURVIVAL_EVALUATION = auto()
PROMOTION = auto()
COMPOSITION_SEARCH = auto()
WORLD_EVALUATION = auto()
CONTRAST_EVALUATION = auto()
STATE_TRANSITION = auto()
#
# Signal layer
#
@dataclass
class Exposure:
One noisy observation of a latent curve.
```
This is NOT the latent curve. The latent curve is never directly
observed. This is a sampled, noise-corrupted projection of it.
No semantic labels are attached.
"""
arm_id: ArmID
exposure_index: int
points: np.ndarray # shape (N, 2) noisy 2D point cloud
sample_params: np.ndarray # shape (N,) s values used for sampling
```
@dataclass
class ExposureStream:
K independent noisy exposures from one signal arm.
The latent curve is not stored here only its projections.
arm_id: ArmID
exposures: List[Exposure]
noise_sigma: float
n_points: int
```
@property
def K(self) -> int:
return len(self.exposures)
```
#
# Transform layer
#
@dataclass
class TransformCandidate:
One candidate lens: a parameterized, lawful, pointwise transform.
```
Lawful means: pointwise, deterministic, non-aggregating,
evidence-preserving. No smoothing. No neighbor-blending.
No kernel averaging.
The transform family is defined by bounded mutation operators,
not by knowledge of the desired outcome.
"""
candidate_id: str
arm_id: ArmID
family_name: str
params: np.ndarray # parameter vector for this candidate
param_bounds: np.ndarray # shape (D, 2) [min, max] per param
generation_born: int = 0
```
#
# Evaluation layer
#
@dataclass
class EvaluationResult:
Result of evaluating one transform candidate against one substrate.
```
is_admissible is checked FIRST and is binary (hard veto).
invariance_score is only meaningful when is_admissible is True.
Comments at every call site must distinguish:
- "excluded for inadmissibility" (hard veto)
- "admissible but non-surviving" (soft failure on invariance)
These are architecturally distinct outcomes.
"""
candidate_id: str
is_admissible: bool
invariance_score: float # undefined / 0.0 when not admissible
failure_reason: Optional[str] # populated when is_admissible is False
diagnostics: Dict[str, Any] = field(default_factory=dict)
```
#
# Promotion layer
#
@dataclass
class PromotedStructure:
A structure that has survived lens search and earned promotion.
```
This object is NO LONGER raw signal. It is an abstract survived
structure eligible for higher-order operations.
It carries provenance (where it came from, how it survived) and
a structural parameterization independent of the original point cloud.
The render_geometry field is a convenience for visualization only.
It does not drive logic.
"""
structure_id: str
origin_arm: ArmID
source_candidate_id: str
# Survived structural parameterization arm-specific interpretation
# but stored in a common container. Comments in promotion.py explain
# what these mean for each arm.
structural_params: Dict[str, Any]
# Support statistics from the survival run
final_invariance_score: float
generations_survived: int
exposures_validated: int
promotion_generation: int
# Admissibility certificate the structure passed world pre-screening
admissibility_certified: bool
# Geometry for rendering passive, does not drive logic
render_geometry: Optional[np.ndarray] = None
```
#
# Composition layer
#
@dataclass
class CompositionCandidate:
One candidate composition of two independently promoted structures.
```
This is NOT arbitrary geometric attachment. Composition is a
relationship between two survived structures, constrained by
compatibility rules. The kernel operating here is the same
survival kernel that operated at the signal level.
Same kernel, new substrate.
"""
candidate_id: str
structure_a: PromotedStructure # from arm 1
structure_b: PromotedStructure # from arm 2
relation_params: np.ndarray # translation, rotation, phase, scale alignment, etc.
param_bounds: np.ndarray
generation_born: int = 0
def describe(self) -> str:
return (f"CompositionCandidate({self.candidate_id}) "
f"arm1={self.structure_a.structure_id} "
f"arm2={self.structure_b.structure_id}")
```
@dataclass
class CompositionResult:
Result of evaluating one composition candidate.
Same admissibility-first logic as EvaluationResult.
candidate_id: str
is_admissible: bool
compatibility_score: float
failure_reason: Optional[str]
survived: bool
diagnostics: Dict[str, Any] = field(default_factory=dict)
@dataclass
class RealizedComposition:
A composition candidate that survived and has been realized
as a concrete geometric object for world evaluation.
```
This is the candidate key. It is not called a key internally
because the system does not know it is a key. It is a survived
composed structure being tested against world constraints.
"""
composition_id: str
source_candidate: CompositionCandidate
geometry: np.ndarray # realized 2D/3D geometry
structural_params: Dict[str, Any]
```
#
# World layer
#
@dataclass
class WorldResult:
Result of evaluating a realized composition against the world constraint.
```
The world enforces constraint equations. It does not recognize
solutions by lookup. Failure modes are constraint violations,
not match failures.
"""
candidate_id: str
can_insert: bool
can_rotate: bool
can_activate: bool
success: bool
failure_mode: FailureMode
mechanism_state_before: Dict[str, Any]
mechanism_state_after: Dict[str, Any]
constraint_diagnostics: Dict[str, Any] = field(default_factory=dict)
```
#
# Survival kernel I/O
#
@dataclass
class SurvivalConfig:
Configuration for one run of the survival kernel.
Same config structure regardless of what substrate the kernel
is operating on.
population_size: int = 40
max_generations: int = 80
elite_fraction: float = 0.15
mutation_rate: float = 0.3
crossover_rate: float = 0.5
promotion_threshold: float = 0.75 # invariance score for promotion
promotion_stability_gens: int = 5 # must hold for this many generations
rng_seed: Optional[int] = None
@dataclass
class SurvivalResult:
Full output of one survival kernel run.
Contains enough state for the renderer to reconstruct every
meaningful moment of the run.
arm_id: Optional[ArmID] # None when running at composition level
stage: StageLabel
config: SurvivalConfig
```
# Per-generation history
population_history: List[List[TransformCandidate]] # or CompositionCandidate
fitness_history: List[List[EvaluationResult]]
best_per_generation: List[float]
# Outcome
promoted: bool
promotion_generation: Optional[int]
promoted_candidate_id: Optional[str]
# Statistics
total_evaluated: int
total_inadmissible: int
total_non_surviving: int
# Actual evolved best candidate returned directly from kernel
# No re-evaluation hack needed downstream
best_candidate_object: Optional[Any] = None
```
#
# Renderer state
#
@dataclass
class RendererSnapshot:
Passive state snapshot for visualization.
```
This object is produced by renderer_state.py reading internal
computational state. It NEVER drives logic. No timer-driven
state changes are permitted every snapshot corresponds to
an actual computational event.
"""
frame_id: int
stage: StageLabel
timestamp_gen: int # generation or step number
# What to show
signal_views: Dict[str, Any] = field(default_factory=dict)
candidate_views: List[Dict] = field(default_factory=list)
fitness_distribution: Optional[np.ndarray] = None
admissibility_failures: int = 0
promoted_views: List[Dict] = field(default_factory=list)
composition_views: List[Dict] = field(default_factory=list)
world_view: Optional[Dict] = None
contrast_view: Optional[Dict] = None
# Sparse on-screen text must match what is actually happening
overlay_text: Optional[str] = None
```