""" Shared utilities for FractalStat validation experiments. Successor to fractalstat with improved expressivity (100% vs 95%). Added 8th dimension: 'alignment' for social/coordination dynamics. Features: - Hybrid encoding (maps legacy systems to FractalStat coordinates) - Backward compatibility with existing pets/badges/entities - LUCA-adjacent bootstrap tracing - Deterministic coordinate assignment - Entanglement detection and management """ from dataclasses import dataclass, field from datetime import datetime, timezone from enum import Enum from typing import Dict, List, Optional, Any, Tuple from pathlib import Path import json import uuid import hashlib from abc import ABC, abstractmethod import secrets import random from decimal import Decimal, ROUND_HALF_EVEN def _utc_now() -> datetime: """Helper function for timezone-aware UTC datetime.""" return datetime.now(timezone.utc) # ============================================================================ # FractalStat Dimension Enums # ============================================================================ class Realm(Enum): """Domain classification for FractalStat entities""" COMPANION = "companion" # Pets, familiars, companions BADGE = "badge" # Achievement badges SPONSOR_RING = "sponsor_ring" # Sponsor tier badges ACHIEVEMENT = "achievement" # Generic achievements PATTERN = "pattern" # System patterns FACULTY = "faculty" # Faculty-exclusive entities TEMPORAL = "temporal" # Time-based entities VOID = "void" # Null/empty realm class Horizon(Enum): """Lifecycle stage in entity progression""" GENESIS = "genesis" # Entity created, initial state EMERGENCE = "emergence" # Entity becoming active PEAK = "peak" # Entity at maximum activity DECAY = "decay" # Entity waning CRYSTALLIZATION = "crystallization" # Entity settled/permanent ARCHIVED = "archived" # Historical record class Polarity(Enum): """Resonance/affinity classification""" # Companion polarities (elemental) LOGIC = "logic" CREATIVITY = "creativity" ORDER = "order" CHAOS = "chaos" BALANCE = "balance" # Badge polarities (category) ACHIEVEMENT = "achievement" CONTRIBUTION = "contribution" COMMUNITY = "community" TECHNICAL = "technical" CREATIVE = "creative" UNITY = "unity" # Special for sponsor rings # Neutral VOID = "void" class Alignment(Enum): """Social and coordination dynamics alignment""" # Classical alignment system (inspired by fantasy RPGs) - Law vs Chaos LAWFUL_GOOD = "lawful_good" # Principled, helpful NEUTRAL_GOOD = "neutral_good" # Helpful, flexible CHAOTIC_GOOD = "chaotic_good" # Helpful, unconstrained LAWFUL_NEUTRAL = "lawful_neutral" # Principled, pragmatic TRUE_NEUTRAL = "true_neutral" # Balanced, pragmatic CHAOTIC_NEUTRAL = "chaotic_neutral" # Flexible, pragmatic LAWFUL_EVIL = "lawful_evil" # Principled, harmful NEUTRAL_EVIL = "neutral_evil" # Self-serving CHAOTIC_EVIL = "chaotic_evil" # Harmful, unconstrained # Special classifications for FractalStat HARMONIC = "harmonic" # Naturally coordinated ENTROPIC = "entropic" # Naturally disruptive SYMBIOTIC = "symbiotic" # Mutually beneficial connections # ============================================================================ # FractalStat Coordinate Data Class (8 Dimensions) # ============================================================================ @dataclass class FractalStatCoordinates: """ 8-dimensional addressing space for all entities with 100% expressivity. Each dimension represents a different axis of entity existence: 1. Realm: Domain/type classification 2. Lineage: Generation or tier progression from LUCA 3. Adjacency: Semantic/functional proximity score (0-100) 4. Horizon: Lifecycle stage 5. Luminosity: Activity level (0-100) 6. Polarity: Resonance/affinity type 7. Dimensionality: Fractal depth / detail level 8. Alignment: Social/coordination dynamics (NEW - 100% expressivity boost) """ realm: Realm # Domain classification lineage: int # 0-based generation from LUCA adjacency: float # 0-100 proximity score horizon: Horizon # lifecycle stage luminosity: float # 0-100 activity level polarity: Polarity # resonance/affinity type dimensionality: int # 0+ fractal depth alignment: Alignment # 8th dimension for social dynamics @property def address(self) -> str: """Generate canonical FractalStat address string""" return f"FractalStat-{self.realm.value[0].upper()}-{self.lineage:03d}-{int(self.adjacency):02d}-{self.horizon.value[0].upper()}-{int(self.luminosity):02d}-{self.polarity.value[0].upper()}-{self.dimensionality}-{self.alignment.value[0].upper()}" @staticmethod def from_address(address: str) -> "FractalStatCoordinates": """Parse FractalStat address back to coordinates""" # Format: FractalStat-R-LLL-AA-H-LL-P-D-A (9 parts total) parts = address.split("-") if len(parts) != 9 or parts[0] != "FractalStat": raise ValueError(f"Invalid FractalStat address: {address}") realm_map = {r.value[0].upper(): r for r in Realm} horizon_map = {h.value[0].upper(): h for h in Horizon} polarity_map = {p.value[0].upper(): p for p in Polarity} alignment_map = {a.value[0].upper(): a for a in Alignment} try: return FractalStatCoordinates( realm=realm_map[parts[1]], lineage=int(parts[2]), adjacency=float(parts[3]), horizon=horizon_map[parts[4]], luminosity=float(parts[5]), polarity=polarity_map[parts[6]], dimensionality=int(parts[7]), alignment=alignment_map[parts[8]], ) except (KeyError, ValueError) as e: raise ValueError(f"Invalid FractalStat address: {address}") from e def to_dict(self) -> Dict[str, Any]: """Convert to dictionary for JSON serialization""" return { "realm": self.realm.value, "lineage": self.lineage, "adjacency": self.adjacency, "horizon": self.horizon.value, "luminosity": self.luminosity, "polarity": self.polarity.value, "dimensionality": self.dimensionality, "alignment": self.alignment.value, "address": self.address, } # ============================================================================ # Lifecycle Event Tracking # ============================================================================ @dataclass class LifecycleEvent: """Record of significant moments in entity history""" timestamp: datetime event_type: str # "birth", "evolution", "mint", etc. description: str metadata: Dict[str, Any] = field(default_factory=dict) def to_dict(self) -> Dict[str, Any]: return { "timestamp": self.timestamp.isoformat(), "event_type": self.event_type, "description": self.description, "metadata": self.metadata, } # ============================================================================ # FractalStat Entity Base Class # ============================================================================ @dataclass class FractalStatEntity(ABC): """ Abstract base class for all FractalStat-addressed entities. 8-dimensional successor to fractalstat with enhanced expressivity. Provides: - Hybrid encoding (bridge between legacy and FractalStat systems) - 8D coordinate assignment - Entanglement tracking - Temporal tracking - NFT metadata """ # Identity entity_id: str = field(default_factory=lambda: str(uuid.uuid4())) entity_type: str = "" # Overridden in subclasses # FractalStat Addressing (8D) fractalstat: Optional[FractalStatCoordinates] = None # Legacy Fields (backward compatibility) legacy_data: Dict[str, Any] = field(default_factory=dict) migration_source: Optional[str] = None # "pet", "badge", etc. # NFT Status nft_minted: bool = False nft_contract: Optional[str] = None nft_token_id: Optional[int] = None nft_metadata_ipfs: Optional[str] = None # Entanglement entangled_entities: List[str] = field(default_factory=list) entanglement_strength: List[float] = field(default_factory=list) # Temporal created_at: datetime = field(default_factory=_utc_now) last_activity: datetime = field(default_factory=_utc_now) lifecycle_events: List[LifecycleEvent] = field(default_factory=list) # Owner/User owner_id: str = "" # User Preferences opt_in_fractalstat_nft: bool = True # Renamed from opt_in_fractalstat_nft opt_in_blockchain: bool = False preferred_zoom_level: int = 1 # Default display level def __post_init__(self): """Initialize FractalStat coordinates if not provided""" if self.fractalstat is None: self.fractalstat = self._compute_fractalstat_coordinates() self._record_event("genesis", "Entity initialized in FractalStat space") # ======================================================================== # Abstract Methods (Implemented by Subclasses) # ======================================================================== @abstractmethod def _compute_fractalstat_coordinates(self) -> FractalStatCoordinates: """ Compute 8D FractalStat coordinates from entity data. Each subclass defines its own coordinate mapping. """ @abstractmethod def to_collectible_card_data(self) -> Dict[str, Any]: """Convert entity to collectible card display format""" @abstractmethod def validate_hybrid_encoding(self) -> Tuple[bool, str]: """ Validate that FractalStat coordinates correctly encode legacy data. Returns (is_valid, error_message_or_empty_string) """ # ======================================================================== # Event Tracking # ======================================================================== def _record_event( self, event_type: str, description: str, metadata: Optional[Dict[str, Any]] = None, ): """Record a lifecycle event""" event = LifecycleEvent( timestamp=datetime.now(timezone.utc), event_type=event_type, description=description, metadata=metadata or {}, ) self.lifecycle_events.append(event) self.last_activity = event.timestamp def get_event_history(self, limit: Optional[int] = None) -> List[LifecycleEvent]: """Get lifecycle events, optionally limited to most recent""" events = sorted(self.lifecycle_events, key=lambda e: e.timestamp, reverse=True) return events[:limit] if limit else events # ======================================================================== # Entanglement Management # ======================================================================== def add_entanglement(self, other_entity_id: str, strength: float = 1.0): """ Link to another entity via resonance/entanglement. Strength: 0-1.0 (1.0 = maximum entanglement) """ if other_entity_id not in self.entangled_entities: self.entangled_entities.append(other_entity_id) self.entanglement_strength.append(strength) self._record_event( "entanglement_added", f"Entangled with {other_entity_id}", {"strength": strength}, ) def remove_entanglement(self, other_entity_id: str): """Remove entanglement with another entity""" if other_entity_id in self.entangled_entities: idx = self.entangled_entities.index(other_entity_id) self.entangled_entities.pop(idx) self.entanglement_strength.pop(idx) self._record_event( "entanglement_removed", f"Untangled from {other_entity_id}" ) def get_entanglements(self) -> List[Tuple[str, float]]: """Get all entangled entities with strength""" return list(zip(self.entangled_entities, self.entanglement_strength)) def update_entanglement_strength(self, other_entity_id: str, new_strength: float): """Update entanglement strength with another entity""" if other_entity_id in self.entangled_entities: idx = self.entangled_entities.index(other_entity_id) old_strength = self.entanglement_strength[idx] self.entanglement_strength[idx] = new_strength self._record_event( "entanglement_updated", f"Entanglement strength changed {old_strength:.2f} -> {new_strength:.2f}", ) # ======================================================================== # LUCA Bootstrap # ======================================================================== @property def luca_distance(self) -> int: """Distance from LUCA (Last Universal Common Ancestor)""" if self.fractalstat is None: raise ValueError("fractalstat coordinates must be initialized") return self.fractalstat.lineage def get_luca_trace(self) -> Dict[str, Any]: """ Get path back to LUCA bootstrap origin. In a real system, this would trace parent entities. """ if self.fractalstat is None: raise ValueError("fractalstat coordinates must be initialized") return { "entity_id": self.entity_id, "luca_distance": self.luca_distance, "realm": self.fractalstat.realm.value, "lineage": self.fractalstat.lineage, "created_at": self.created_at.isoformat(), "migration_source": self.migration_source, "event_count": len(self.lifecycle_events), } # ======================================================================== # NFT Integration # ======================================================================== def prepare_for_minting(self) -> Dict[str, Any]: """ Generate NFT metadata for minting. Returns ERC-721/ERC-1155 compatible metadata object. """ if not self.opt_in_fractalstat_nft: raise ValueError("Entity not opted in to FractalStat-NFT system") if self.fractalstat is None: raise ValueError("fractalstat coordinates must be initialized") card_data = self.to_collectible_card_data() return { "name": card_data.get("title", self.entity_id), "description": card_data.get("fluff_text", ""), "image": card_data.get("artwork_url", ""), "external_url": f"https://theseed.example.com/entity/{self.entity_id}", "attributes": [ {"trait_type": "Entity Type", "value": self.entity_type}, {"trait_type": "Realm", "value": self.fractalstat.realm.value}, {"trait_type": "Lineage", "value": self.fractalstat.lineage}, {"trait_type": "Horizon", "value": self.fractalstat.horizon.value}, { "trait_type": "Luminosity", "value": int(self.fractalstat.luminosity), }, {"trait_type": "Polarity", "value": self.fractalstat.polarity.value}, { "trait_type": "Dimensionality", "value": self.fractalstat.dimensionality, }, {"trait_type": "Alignment", "value": self.fractalstat.alignment.value}, { "trait_type": "FractalStat Address", "value": self.fractalstat.address, }, ], "properties": card_data.get("properties", {}), } def record_mint(self, contract_address: str, token_id: int, ipfs_hash: str): """Record successful NFT minting""" self.nft_minted = True self.nft_contract = contract_address self.nft_token_id = token_id self.nft_metadata_ipfs = ipfs_hash self._record_event( "nft_minted", f"Minted as ERC-721 token #{token_id}", { "contract": contract_address, "token_id": token_id, "ipfs_hash": ipfs_hash, }, ) # ======================================================================== # Serialization # ======================================================================== def to_dict(self) -> Dict[str, Any]: """Convert entity to dictionary for JSON storage""" return { "entity_id": self.entity_id, "entity_type": self.entity_type, "fractalstat": self.fractalstat.to_dict() if self.fractalstat else None, "legacy_data": self.legacy_data, "migration_source": self.migration_source, "nft_minted": self.nft_minted, "nft_contract": self.nft_contract, "nft_token_id": self.nft_token_id, "nft_metadata_ipfs": self.nft_metadata_ipfs, "entangled_entities": self.entangled_entities, "entanglement_strength": self.entanglement_strength, "created_at": self.created_at.isoformat(), "last_activity": self.last_activity.isoformat(), "lifecycle_events": [e.to_dict() for e in self.lifecycle_events], "owner_id": self.owner_id, "opt_in_fractalstat_nft": self.opt_in_fractalstat_nft, "opt_in_blockchain": self.opt_in_blockchain, "preferred_zoom_level": self.preferred_zoom_level, } def save_to_file(self, path: Path): """Persist entity to JSON file""" path.parent.mkdir(parents=True, exist_ok=True) with open(path, "w", encoding="utf-8") as f: json.dump(self.to_dict(), f, indent=2, default=str) @classmethod def load_from_file(cls, path: Path) -> "FractalStatEntity": """Load entity from JSON file (must know concrete type)""" with open(path, "r", encoding="utf-8") as f: data = json.load(f) entity_type = data.get("entity_type", "unknown") raise NotImplementedError( f"Use subclass load methods (detected entity_type: {entity_type}). " "Use factory pattern to instantiate correct subclass." ) # ======================================================================== # Display Levels # ======================================================================== def render_zoom_level(self, level: int) -> Dict[str, Any]: """ Render entity at specific zoom level. Level 1: Badge (20x20px icon) Level 2: Dog-tag (100x150px micro-card) Level 3: Collectible Card (300x400px full card) Level 4: Profile panel (350x500px interactive) Level 5: Entity profile page (full details) Level 6+: Fractal descent (dimension breakdown) """ if level < 1 or level > 8: # Increased max zoom level for 8D raise ValueError(f"Invalid zoom level: {level}") if self.fractalstat is None: raise ValueError("FractalStat coordinates must be initialized") card_data = self.to_collectible_card_data() base = { "zoom_level": level, "entity_id": self.entity_id, "fractalstat_address": self.fractalstat.address, "created_at": self.created_at.isoformat(), } if level == 1: # Badge: Just icon + rarity return { **base, "type": "badge", "icon": card_data.get("icon_url"), "rarity": card_data.get("rarity"), } elif level == 2: # Dog-tag: Icon, title, key stats return { **base, "type": "dog_tag", "icon": card_data.get("icon_url"), "title": card_data.get("title"), "stats": card_data.get("key_stats"), } elif level == 3: # Full card return {**base, "type": "collectible_card", **card_data} elif level == 4: # Profile panel return { **base, "type": "profile_panel", **card_data, "owner": self.owner_id, "entangled_count": len(self.entangled_entities), "events": len(self.lifecycle_events), } elif level == 5: # Full profile page return { **base, "type": "entity_profile", **card_data, "owner": self.owner_id, "lifecycle_events": [e.to_dict() for e in self.lifecycle_events], "entanglements": self.get_entanglements(), "luca_trace": self.get_luca_trace(), } elif level == 6: # 8th dimension awareness return { **base, "type": "fractal_descent", "fractalstat_dimensions": self.fractalstat.to_dict(), "alignment_dynamics": self._get_alignment_details(), "realm_details": self._get_realm_details(), "entanglement_network": self.get_entanglements(), "event_chronology": [e.to_dict() for e in self.lifecycle_events], "luca_trace": self.get_luca_trace(), } else: # level 7+ # Full fractal descent with 8D awareness return { **base, "type": "fractal_descent", "fractalstat_dimensions": self.fractalstat.to_dict(), "alignment_dynamics": self._get_alignment_details(), "realm_details": self._get_realm_details(), "entanglement_network": self.get_entanglements(), "event_chronology": [e.to_dict() for e in self.lifecycle_events], "luca_trace": self.get_luca_trace(), } def _get_realm_details(self) -> Dict[str, Any]: """Override in subclasses to provide realm-specific details""" return {} def _get_alignment_details(self) -> Dict[str, Any]: """Get alignment-based social/coordination analysis""" if self.fractalstat is None: return {} alignment = self.fractalstat.alignment # Analyze social coordination patterns based on alignment coordination_style = { Alignment.LAWFUL_GOOD: "structured_harmonious", Alignment.NEUTRAL_GOOD: "balanced_harmonious", Alignment.CHAOTIC_GOOD: "flexible_harmonious", Alignment.LAWFUL_NEUTRAL: "structured_pragmatic", Alignment.TRUE_NEUTRAL: "balanced_pragmatic", Alignment.CHAOTIC_NEUTRAL: "flexible_pragmatic", Alignment.LAWFUL_EVIL: "structured_destructive", Alignment.NEUTRAL_EVIL: "balanced_destructive", Alignment.CHAOTIC_EVIL: "flexible_destructive", Alignment.HARMONIC: "naturally_coordinating", Alignment.ENTROPIC: "naturally_disruptive", Alignment.SYMBIOTIC: "mutually_beneficial", }.get(alignment, "unknown") return { "alignment": alignment.value, "coordination_style": coordination_style, "social_dynamics": self._analyze_social_dynamics(), } def _analyze_social_dynamics(self) -> Dict[str, Any]: """Analyze social interaction patterns based on entanglement and alignment""" if self.fractalstat is None: return {} # Simplified social analysis based on alignment alignment = self.fractalstat.alignment if alignment in [Alignment.LAWFUL_GOOD, Alignment.HARMONIC]: social_pattern = "coordinating_harmonious" elif alignment in [Alignment.CHAOTIC_EVIL, Alignment.ENTROPIC]: social_pattern = "disruptive_chaotic" else: social_pattern = "pragmatic_balanced" return { "social_pattern": social_pattern, "entanglement_quality": len(self.entangled_entities) * 0.1, # Simplified metric "coordination_potential": self._calculate_coordination_potential(), } def _calculate_coordination_potential(self) -> float: """Calculate coordination potential based on alignment and entanglements""" # Simplified calculation - would be more sophisticated in production base_potential = len(self.entangled_entities) * 0.1 # Alignment modifiers alignment_bonus = { Alignment.HARMONIC: 1.5, Alignment.SYMBIOTIC: 1.3, Alignment.LAWFUL_GOOD: 1.2, Alignment.CHAOTIC_EVIL: -0.5, Alignment.ENTROPIC: -0.3, }.get( self.fractalstat.alignment if self.fractalstat else Alignment.TRUE_NEUTRAL, 1.0, ) return min(1.0, base_potential * alignment_bonus) # ============================================================================ # Helper Functions # ============================================================================ def hash_for_coordinates(data: Dict[str, Any]) -> str: """Deterministic hashing for coordinate assignment""" json_str = json.dumps(data, sort_keys=True) return hashlib.sha256(json_str.encode()).hexdigest() def compute_adjacency_score(tags1: List[str], tags2: List[str]) -> float: """ Compute adjacency (similarity) score between two tag sets. Returns 0-100 score. """ if not tags1 or not tags2: return 0.0 common = len(set(tags1) & set(tags2)) total = len(set(tags1) | set(tags2)) return (common / total) * 100 if total > 0 else 0.0 # ============================================================================ # BitChain Entity (moved from fractalstat_experiments to break circular import) # ============================================================================ class DataClass(Enum): """Data sensitivity classification.""" PUBLIC = "PUBLIC" # Anyone can read SENSITIVE = "SENSITIVE" # Authenticated users, role-based PII = "PII" # Owner-only, requires 2FA class Capability(Enum): """Recovery capability levels.""" COMPRESSED = "compressed" # Read-only mist form, no expansion PARTIAL = "partial" # Anonymized expansion, limited fields FULL = "full" # Complete recovery # Coordinate data class for BitChain (different from FractalStatCoordinates) @dataclass class Coordinates: """FractalStat 8-dimensional coordinates with enhanced expressivity.""" realm: str # Domain: data, narrative, system, faculty, event, pattern, void, temporal lineage: int # Generation from LUCA adjacency: List[str] # Relational neighbors (append-only) horizon: str # Lifecycle stage luminosity: float # 0-100 activity level polarity: Polarity # Resonance/affinity type dimensionality: int # 0+ fractal depth alignment: Alignment # Social alignment dynamics - NEW DIMENSION def to_dict(self) -> Dict[str, Any]: """Convert to canonical dict with normalized floats.""" return { # Append-only, but stored sorted "realm": self.realm, "lineage": self.lineage, "adjacency": sorted(self.adjacency), "horizon": self.horizon, "luminosity": normalize_float(self.luminosity), "polarity": self.polarity.name, "dimensionality": self.dimensionality, "alignment": self.alignment.name, } @dataclass class BitChain: """ Minimal addressable unit in FractalStat space. Represents a single entity instance (manifestation). Security fields (Phase 1 Doctrine: Authentication + Access Control): - data_classification: Sensitivity level (PUBLIC, SENSITIVE, PII) - access_control_list: Roles allowed to recover this bitchain - owner_id: User who owns this bitchain - encryption_key_id: Optional key for encrypted-at-rest data """ id: str # Unique entity ID entity_type: str # Type: concept, artifact, agent, etc. realm: str # Domain classification coordinates: Coordinates # FractalStat 8D position created_at: str # ISO8601 UTC timestamp state: Dict[str, Any] # Mutable state data # Security fields (Phase 1) data_classification: DataClass = DataClass.PUBLIC access_control_list: List[str] = field(default_factory=lambda: ["owner"]) owner_id: Optional[str] = None encryption_key_id: Optional[str] = None def __post_init__(self): """Normalize timestamps.""" self.created_at = normalize_timestamp(self.created_at) def to_canonical_dict(self) -> Dict[str, Any]: """Convert to canonical form for hashing.""" return { "created_at": self.created_at, "entity_type": self.entity_type, "id": self.id, "realm": self.realm, "fractalstat_coordinates": self.coordinates.to_dict(), "state": sort_json_keys(self.state), } def compute_address(self) -> str: """Compute this bit-chain's FractalStat address (hash).""" return compute_address_hash(self.to_canonical_dict()) def get_fractalstat_uri(self) -> str: """Generate FractalStat URI address format.""" coords = self.coordinates adjacency_hash = compute_address_hash({"adjacency": sorted(coords.adjacency)})[ :8 ] uri = ( f"fractalstat://{coords.realm}/{coords.lineage}/{adjacency_hash}/{coords.horizon}" ) uri += f"?r={normalize_float(coords.luminosity)}&p={coords.polarity.name}" uri += f"&d={coords.dimensionality}&s={self.id}&a={coords.alignment.name}" return uri # ============================================================================ # Constants and utilities for BitChain (moved from fractalstat_experiments) # ============================================================================ # Use cryptographically secure random number generator secure_random = secrets.SystemRandom() REALMS = ["data", "narrative", "system", "faculty", "event", "pattern", "void"] HORIZONS = ["genesis", "emergence", "peak", "decay", "crystallization"] POLARITY_LIST = ["logic", "creativity", "order", "chaos", "balance", "achievement", "contribution", "community", "technical", "creative", "unity", "void"] ALIGNMENT_LIST = ["lawful_good", "neutral_good", "chaotic_good", "lawful_neutral", "true_neutral", "chaotic_neutral", "lawful_evil", "neutral_evil"] ENTITY_TYPES = [ "concept", "artifact", "agent", "lineage", "adjacency", "horizon", "fragment", ] def normalize_float(value: float, decimal_places: int = 8) -> str: """ Normalize floating point to 8 decimal places using banker's rounding. """ if isinstance(value, float): if value != value or value == float("inf") or value == float("-inf"): raise ValueError(f"NaN and Inf not allowed: {value}") # Use Decimal for precise rounding d = Decimal(str(value)) quantized = d.quantize(Decimal(10) ** -decimal_places, rounding=ROUND_HALF_EVEN) # Convert to string and strip trailing zeros result = str(quantized) if "." in result: result = result.rstrip("0") if result.endswith("."): result += "0" elif "E" in result or "e" in result: # Handle scientific notation result = "0.0" return result def normalize_timestamp(ts: Optional[str] = None) -> str: """ Normalize timestamp to ISO8601 UTC with millisecond precision. """ if ts is None: now = datetime.now(timezone.utc) return now.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" else: # Parse input timestamp and convert to UTC if ts.endswith("Z"): ts = ts[:-1] + "+00:00" now = datetime.fromisoformat(ts).astimezone(timezone.utc) # Format with millisecond precision return now.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" def sort_json_keys(obj: Any) -> Any: """ Recursively sort all JSON object keys in ASCII order (case-sensitive). """ if isinstance(obj, dict): return {k: sort_json_keys(obj[k]) for k in sorted(obj.keys())} elif isinstance(obj, list): return [sort_json_keys(item) for item in obj] else: return obj def canonical_serialize(data: Dict[str, Any]) -> str: """ Serialize to canonical form for deterministic hashing. """ sorted_data = sort_json_keys(data) canonical = json.dumps( sorted_data, separators=(",", ":"), ensure_ascii=True, sort_keys=False ) return canonical def compute_address_hash(data: Dict[str, Any]) -> str: """ Compute SHA-256 hash of canonical serialization. """ canonical = canonical_serialize(data) return hashlib.sha256(canonical.encode("utf-8")).hexdigest() def generate_random_bitchain(seed: Optional[int] = None) -> BitChain: """ Generate a random bit-chain for testing and validation experiments. """ # Use seedable random when seed is provided, otherwise use secure random if seed is not None: rng = random.Random(seed) base_id = hashlib.sha256(str(seed).encode()).hexdigest()[:32] id_str = f"{base_id[:8]}-{base_id[8:12]}-{base_id[12:16]}-{base_id[16:20]}" id_str += f"-{base_id[20:32]}" created_at_str = f"2024-01-01T{seed % 24:02d}:{(seed // 24) % 60:02d}" created_at_str += f":{(seed // 1440) % 60:02d}.000Z" else: rng = secure_random id_str = str(uuid.uuid4()) created_at_str = datetime.now(timezone.utc).isoformat() # Replace all instances of `secure_random.` with `rng.` in the rest of the function adjacency_ids = [ ( hashlib.sha256(f"{seed}-adj-{i}".encode()).hexdigest()[:32] if seed is not None else str(uuid.uuid4()) ) for i in range(rng.randint(0, 5)) # Changed from secure_random.randint ] if seed is not None and adjacency_ids: adjacency_ids = [ f"{uuid_hex[:8]}-{uuid_hex[8:12]}-{uuid_hex[12:16]}-{uuid_hex[16:20]}" f"-{uuid_hex[20:32]}" for uuid_hex in adjacency_ids ] # Generate coordinates with alignment luminosity_val = rng.uniform(0, 100) # Changed from secure_random.uniform polarity_val = rng.choice(POLARITY_LIST) # Changed from secure_random.choice dimensionality_val = rng.randint(0, 5) # Changed from secure_random.randint alignment_val = rng.choice(list(Alignment)) # Changed from secure_random.choice return BitChain( id=id_str, entity_type=rng.choice(ENTITY_TYPES), # Changed from secure_random.choice realm=rng.choice(REALMS), # Changed from secure_random.choice coordinates=Coordinates( realm=rng.choice(REALMS), # Changed from secure_random.choice lineage=rng.randint(1, 100), # Changed from secure_random.randint adjacency=adjacency_ids, horizon=rng.choice(HORIZONS), # Changed from secure_random.choice luminosity=luminosity_val, polarity=Polarity[polarity_val.upper()], dimensionality=dimensionality_val, alignment=alignment_val, ), created_at=created_at_str, state={"value": rng.randint(0, 1000)}, # Changed from secure_random.randint )