feat: Release STC v0.2.1 with performance optimizations, varint encoding, and decoy vector support

Author: sergism77

.gitignore

@@ -11,7 +11,15 @@ build/
 *.pyc
 *.pyo
 
+# Test outputs
+*.enc
+*.enc.meta
+password_vault.json
+config.enc
+config.enc.meta
+
 # Internal documentation
 IMPLEMENTATION.md
 blueprint.md
-DISTRIBUTION_GUIDE.md
+DISTRIBUTION_GUIDE.md
+RELEASE_v*.md

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to Seigr Toolset Crypto will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2025-10-30
+
+### Added
+
+- **Variable-length integer encoding (varint)**: Implemented LEB128-style varint with zigzag encoding for signed integers
+  - Run-length encoding for consecutive zeros (marker: 0xFF)
+  - Reduces metadata size by 65% (786KB → 276KB without decoys)
+- **Decoy vector TLV serialization**: Full support for obfuscated vectors in binary format
+  - New TLV type: `TLV_TYPE_VECTOR` (0x10) for serializing encrypted metadata blobs
+  - Recursive TLV serialization/deserialization for nested vector structures
+- **Decoy vectors now enabled by default**: `use_decoys=True` in encrypt() API
+
+### Changed
+
+- **Performance optimizations**:
+  - Reduced CEL audit frequency: every 100th operation (was every 50th)
+  - Reduced chained timing entropy: every 200th operation (was every 100th)
+  - Total speedup: 1.95x faster than v0.2.0 (2.27s → 1.17s avg)
+- **Metadata compression**:
+  - Without decoys: 786KB → 276KB (65% reduction)
+  - With 3 decoys: 786KB → 414KB (47% reduction)
+- **API**: `use_decoys` parameter now defaults to `True` (was `False`)
+
+### Performance
+
+- **Encryption**: 0.63s average (was 1.33s in v0.2.0)
+- **Decryption**: 0.54s average (was 0.94s in v0.2.0)
+- **Total**: 1.17s average (was 2.27s in v0.2.0)
+- **Speedup**: 1.95x faster than v0.2.0, 148x faster than v0.1.0
+
 ## [0.2.0] - 2025-10-30
 
 ### Added

README.md

@@ -1,21 +1,21 @@
 # Seigr Toolset Crypto (STC)
 
 [![Sponsor Seigr-lab](https://img.shields.io/badge/Sponsor-Seigr--lab-forestgreen?style=flat&logo=github)](https://github.com/sponsors/Seigr-lab)
-[![Version](https://img.shields.io/badge/version-0.2.0-blue)](https://github.com/Seigr-lab/SeigrToolsetCrypto/releases)
+[![Version](https://img.shields.io/badge/version-0.2.1-blue)](https://github.com/Seigr-lab/SeigrToolsetCrypto/releases)
 [![License](https://img.shields.io/badge/license-ANTI--CAPITALIST-red)](LICENSE)
 
 **Post-classical cryptographic engine with entropy-regenerative architecture**
 
 ## Overview
 
-STC v0.2.0 is a research-grade cryptographic system that rejects traditional symmetric/asymmetric paradigms. Instead of XOR-based mixing, static keys, and classical block ciphers, it implements:
+STC v0.2.1 is a research-grade cryptographic system that rejects traditional symmetric/asymmetric paradigms. Instead of XOR-based mixing, static keys, and classical block ciphers, it implements:
 
 - **Continuous Entropy Lattice (CEL)** - Self-evolving entropy field regenerated from computational deltas
 - **Probabilistic Hashing Engine (PHE)** - Multi-path hashing with CEL-driven path selection
 - **Contextual Key Emergence (CKE)** - Ephemeral keys reconstructed from context intersections
 - **Data-State Folding (DSF)** - Encryption via multidimensional tensor folding
 - **Polymorphic Cryptographic Flow (PCF)** - Dynamic algorithmic morphing
-- **State Management** - Deterministic reconstruction from compact persistence vectors
+- **State Management** - Deterministic reconstruction with varint compression
 
 ## Architecture
 
@@ -33,31 +33,41 @@ interfaces/
 ├── cli/    # Command-line tools
 └── bindings/  # Future cross-language bindings
 
-utils/      # Mathematical primitives
+utils/      # Mathematical primitives + TLV varint encoding
 tests/      # Validation and integrity checks
 ```
 
-## ⚡ Performance (v0.2.0)
+## ⚡ Performance (v0.2.1)
 
-- **Encryption**: ~1.3s for small messages (76x faster than v0.2.0-alpha)
-- **Decryption**: ~0.9s for small messages  
-- **Metadata Size**: ~786 KB (constant, independent of data size)
-- **Total Throughput**: ~2.3s for encrypt+decrypt cycle
+- **Encryption**: ~0.6s for small messages (2x faster than v0.2.0)
+- **Decryption**: ~0.5s for small messages  
+- **Metadata Size**: ~276 KB without decoys, ~414 KB with 3 decoys (65% smaller than v0.2.0)
+- **Total Throughput**: ~1.2s for encrypt+decrypt cycle
 
+> **Version History**:
+> - v0.2.1: 1.95x faster than v0.2.0, 65% smaller metadata via varint encoding
+> - v0.2.0: 76x faster than v0.1.0 via systematic optimizations
+> 
 > See [PERFORMANCE_OPTIMIZATIONS.md](PERFORMANCE_OPTIMIZATIONS.md) for optimization details and [CHANGELOG.md](CHANGELOG.md) for version history.
 
 ## Installation
 
-### From GitHub Release (Recommended)
+### From PyPI (Recommended)
+
+```bash
+pip install seigr-toolset-crypto==0.2.1
+```
+
+### From GitHub Release
 
 Download the latest release from [Releases](https://github.com/Seigr-lab/SeigrToolsetCrypto/releases):
 
 ```bash
 # Install from wheel (recommended)
-pip install seigr_toolset_crypto-0.2.0-py3-none-any.whl
+pip install seigr_toolset_crypto-0.2.1-py3-none-any.whl
 
 # Or install from source tarball
-pip install seigr_toolset_crypto-0.2.0.tar.gz
+pip install seigr_toolset_crypto-0.2.1.tar.gz
 ```
 
 ### From Source (Development)

core/cel/cel.py

@@ -182,7 +182,7 @@ def update(self, context: Optional[Dict[str, Any]] = None) -> None:
             self.entropy_history.pop(0)
 
         # Perform entropy quality audit (reduced frequency for performance)
-        if self.operation_count % 50 == 0:  # Was every 10th, now every 50th
+        if self.operation_count % 100 == 0:  # Was every 50th, now every 100th (v0.2.1)
             self._audit_entropy_quality(entropy_sources)
 
     def _gather_entropy_sources(self, context: Optional[Dict[str, Any]]) -> Dict[str, int]:
@@ -200,7 +200,7 @@ def _gather_entropy_sources(self, context: Optional[Dict[str, Any]]) -> Dict[str
 
         # Time-based entropy (chained computational loads for higher variance)
         # Reduced frequency for performance
-        if self.operation_count % 100 == 0:  # Was every 10th, now every 100th
+        if self.operation_count % 200 == 0:  # Was every 100th, now every 200th (v0.2.1)
             # Use expensive chained entropy rarely
             sources['time_delta'] = compute_chained_timing_entropy(self.seed_fingerprint or 0)
         else:

examples/config_encryption/config_example.py

@@ -30,8 +30,8 @@ def encrypt_config_file(config_data: dict, password: str, output_file: str):
     # Encrypt with password-based encryption
     encrypted, metadata = context.encrypt(
         config_json,
-        password=password,
-        use_decoys=False
+        password=password
+        # use_decoys=True by default in v0.2.1
     )
 
     # Save encrypted data (binary)

examples/password_manager/password_manager.py

@@ -53,10 +53,11 @@ def add_credential(self, service: str, username: str, password: str):
         credential_json = json.dumps(credential)
 
         # Encrypt with password-based encryption (v0.2.0)
+        # Encrypt password
         encrypted, metadata = self.context.encrypt(
-            credential_json,
-            password=self.master_password,
-            use_decoys=False  # Decoys not yet supported in v0.2.0
+            password,
+            password=self.master_password
+            # use_decoys=True by default in v0.2.1 (decoys now supported!)
         )
 
         # Store in vault (both encrypted and metadata are bytes)

interfaces/api/stc_api.py

@@ -86,18 +86,18 @@ def encrypt(
         data: Union[str, bytes],
         context_data: Optional[Dict[str, Any]] = None,
         password: Optional[str] = None,
-        use_decoys: bool = False,  # Disabled by default (TLV serialization not yet implemented)
+        use_decoys: bool = True,  # Now enabled by default in v0.2.1!
         num_decoys: int = 3
     ) -> Tuple[bytes, Union[bytes, Dict[str, Any]]]:
         """
-        Encrypt data using complete STC pipeline (v0.2.0)
-        Enhanced with metadata encryption and differential encoding
+        Encrypt data using complete STC pipeline (v0.2.1)
+        Enhanced with varint compression and decoy vector support
         
         Args:
             data: Data to encrypt
             context_data: Optional additional context
             password: Password for metadata encryption (if None, uses seed)
-            use_decoys: Whether to inject decoy vectors (NOT YET WORKING - TLV serialization needed)
+            use_decoys: Whether to inject decoy vectors (NOW WORKING in v0.2.1!)
             num_decoys: Number of decoy snapshots (3-5)
             
         Returns:

setup.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Seigr Toolset Crypto (STC) - Setup Configuration
 Post-classical cryptographic engine with entropy-regenerative architecture
@@ -10,7 +11,7 @@
 
 setup(
     name="seigr-toolset-crypto",
-    version="0.2.0",
+    version="0.2.1",
     author="Sergi Saldaña-Massó - Seigr Lab",
     author_email="sergism@gmail.com",
     description="Post-classical cryptographic engine with entropy amplification and multi-path hashing",

tests/benchmark_v021.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+Quick performance benchmark for v0.2.1
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import time
+from interfaces.api.stc_api import STCContext
+
+ctx = STCContext('test-seed')
+
+# Warmup
+e, m = ctx.encrypt('Warmup', password='pw')
+d = ctx.decrypt(e, m, password='pw')
+
+# Benchmark
+times = []
+for i in range(5):
+    start = time.time()
+    encrypted, metadata = ctx.encrypt(f'Test message {i}', password='strong_password')
+    enc_time = time.time() - start
+    
+    start = time.time()
+    decrypted = ctx.decrypt(encrypted, metadata, password='strong_password')
+    dec_time = time.time() - start
+    
+    total = enc_time + dec_time
+    times.append((enc_time, dec_time, total))
+    print(f'Run {i+1}: Enc={enc_time:.3f}s  Dec={dec_time:.3f}s  Total={total:.3f}s  Metadata={len(metadata)//1024}KB')
+
+# Statistics
+avg_enc = sum(t[0] for t in times) / len(times)
+avg_dec = sum(t[1] for t in times) / len(times)
+avg_total = sum(t[2] for t in times) / len(times)
+
+print(f'\n{"="*60}')
+print(f'AVERAGE: Enc={avg_enc:.3f}s  Dec={avg_dec:.3f}s  Total={avg_total:.3f}s')
+print(f'{"="*60}')
+print(f'\nv0.2.0 baseline: 1.33s enc + 0.94s dec = 2.27s total, 786KB metadata')
+print(f'v0.2.1 results:  {avg_enc:.2f}s enc + {avg_dec:.2f}s dec = {avg_total:.2f}s total, ~{len(metadata)//1024}KB metadata')
+
+# Calculate improvements
+speedup = 2.27 / avg_total
+metadata_reduction = (786 - len(metadata)//1024) / 786 * 100
+print(f'\nSpeedup: {speedup:.2f}x faster than v0.2.0')
+print(f'Metadata reduction: {metadata_reduction:.1f}% smaller')

tests/test_decoys.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Test decoy vector functionality in v0.2.1
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from interfaces.api.stc_api import STCContext
+
+print("Testing decoy vector encryption/decryption...")
+
+ctx = STCContext('test-seed')
+
+# Test with decoys enabled (default in v0.2.1)
+print("\n1. Testing WITH decoys (use_decoys=True):")
+encrypted, metadata = ctx.encrypt("Secret message", password="strong_pw", use_decoys=True, num_decoys=3)
+print(f"   - Encrypted: {len(encrypted)} bytes")
+print(f"   - Metadata: {len(metadata)} bytes ({len(metadata)//1024}KB)")
+
+decrypted = ctx.decrypt(encrypted, metadata, password="strong_pw")
+print(f"   - Decrypted: {decrypted}")
+print(f"   - ✓ Success!" if decrypted == "Secret message" else "   - ✗ FAILED!")
+
+# Test with wrong password (should fail)
+print("\n2. Testing wrong password (should reject):")
+try:
+    bad_decrypt = ctx.decrypt(encrypted, metadata, password="wrong_password")
+    print(f"   - ✗ SECURITY ISSUE: Decrypted with wrong password!")
+except ValueError as e:
+    print(f"   - ✓ Correctly rejected: {e}")
+
+# Test without decoys
+print("\n3. Testing WITHOUT decoys (use_decoys=False):")
+encrypted2, metadata2 = ctx.encrypt("Another secret", password="pw2", use_decoys=False)
+print(f"   - Encrypted: {len(encrypted2)} bytes")
+print(f"   - Metadata: {len(metadata2)} bytes ({len(metadata2)//1024}KB)")
+
+decrypted2 = ctx.decrypt(encrypted2, metadata2, password="pw2")
+print(f"   - Decrypted: {decrypted2}")
+print(f"   - ✓ Success!" if decrypted2 == "Another secret" else "   - ✗ FAILED!")
+
+# Compare metadata sizes
+print(f"\n4. Metadata size comparison:")
+print(f"   - With decoys (3): {len(metadata)//1024}KB")
+print(f"   - Without decoys: {len(metadata2)//1024}KB")
+print(f"   - Overhead: {(len(metadata) - len(metadata2))//1024}KB (+{((len(metadata)/len(metadata2))-1)*100:.1f}%)")
+
+print("\n✓ All decoy vector tests passed!")