# Release Notes

This document tracks release notes and checklists for PyFulmen releases.

## [Unreleased]

### [0.1.13] - PyPI Distribution Workflow - 2025-11-29

**Release Type**: Operational Hardened Release Pipeline

**Summary**: Ships the end-to-end PyPI publishing workflow so PyFulmen
artifacts can be built, verified, and promoted with repeatable automation.
Includes `make prepublish` gating, distribution validation scripts, TestPyPI /
PyPI publish targets, and documentation to walk release drivers through the
process.

#### Highlights

- `make prepublish` now builds sdists/wheels, runs uv + pip install smoke tests,
  and records a sentinel consumed by `make release-check`.
- Helper scripts (`verify_dist_contents.py`, `verify_local_install.py`,
  `verify_published_package.py`, `prepublish_sentinel.py`) catch issues before a
  tag is created or artifacts are uploaded.
- Publishing guide + checklist detail the workflow, required env vars, and
  verification steps for TestPyPI/PyPI.
- Packaging fixes bundle Crucible config/schemas and ensure runtime catalog
  discovery works when importing from a clean environment.
- Twine uploads now target only wheels and sdists, preventing
  `SHA256SUMS.txt` from breaking PyPI uploads.

**Status**: ✅ Released (PyPI `pyfulmen==0.1.13`)

### [0.1.11] - Fulpack Archive Module & Crucible Sync - 2025-11-19

**Release Type**: Major Feature Enhancement - Archive Operations & Infrastructure
**Release Date**: November 19, 2025
**Status**: ✅ Ready for Release

**Summary**: PyFulmen v0.1.11 introduces the **Fulpack** archive module, a security-first canonical interface for archive operations (`tar`, `tar.gz`, `zip`, `gzip`). It also includes a major infrastructure update with **Crucible v0.2.19** integration, bringing the latest ecosystem standards and schemas.

#### Key Features

**📦 Fulpack Archive Module**:

- **Canonical API**: Consistent `create`, `extract`, `scan`, `verify`, `info` operations across all formats
- **Security by Default**:
  - **Zip Slip Protection**: Mandatory path traversal prevention
  - **Zip Bomb Guard**: Decompression bomb detection with configurable limits
  - **Symlink Validation**: Prevention of escaping symlinks
- **Format Support**:
  - `tar.gz` / `tgz` (Common)
  - `zip` (Common)
  - `gzip` (Single file compression)
  - `tar` (Uncompressed)
- **Pluggable Architecture**: Extensible format registry for future formats (7z, brotli, etc.)
- **Crucible Compliance**: Validated against v0.2.13 programmatic fixtures

**🔐 FulHash & Security Updates**:

- **CRC32 Support**: Added `crc32` (zlib) and `crc32c` (google-crc32c) algorithms
- **Verification API**: New `verify(source, expected)` helper for integrity checks
- **MultiHash API**: New `multi_hash(source, algos)` for single-pass multiple digests
- **Fulpack Integration**: Retrofitted `compute_checksum` to use FulHash for supported algorithms
- **Dependencies**: Added `google-crc32c` for hardware-accelerated CRC32C

**🔄 Crucible v0.2.19 Sync**:

- **Infrastructure Update**: Synced latest assets from Crucible SSOT
- **DevSecOps Standards**: New secrets management standards and schemas
- **Logging Schema**: Updates to observability logging schema
- **Type Generation**: Updated generated types/options for Fulpack and other modules

#### Quality Gates

- [x] **Tests**: 50 new fulpack tests (100% pass rate), 6 new fulhash CRC tests, 1707 total tests passing
- [x] **Coverage**: 84% coverage on new fulpack module
- [x] **Security**: Verified protection against Zip Slip and Zip Bomb attacks
- [x] **Documentation**: Comprehensive module guide, examples, and README updates

#### Breaking Changes

- None (fully backward compatible with v0.1.10)

### [0.1.10] - Sync Infrastructure & Architecture Fix - 2025-11-08

**Release Type**: Infrastructure & Architecture Fix
**Release Date**: November 8, 2025
**Status**: ✅ Ready for Release

**Summary**: PyFulmen v0.1.10 resolves critical architectural issues with sync infrastructure and directory separation. This release implements proper separation between custom implementation and Crucible-synced assets, following TSFulmen patterns, and upgrades goneat to v0.3.4 with force_remote configuration for reproducible builds.

#### Key Fixes

**🔧 Critical Architecture Fix**:

- **Directory Separation**: Proper separation between `src/pyfulmen/` (custom implementation) and `src/crucible/` (synced assets)
- **Sync Configuration**: Fixed `.goneat/ssot-consumer.yaml` to sync Crucible Python assets to `src/crucible/pyfulmen/`
- **Import Path Updates**: Updated PyFulmen foundry module to import `exit_codes.py` from correct Crucible location
- **TSFulmen Pattern Compliance**: Now follows same directory structure as TSFulmen and gofulmen

**📦 Goneat Upgrade**:

- **goneat v0.3.4**: Upgraded from v0.3.0 with latest security patches and features
- **force_remote Configuration**: Added `force_remote: true` to prevent dangerous local folder usage
- **Crucible v0.2.8 Pin**: Maintained proper version pinning for reproducible builds
- **Sync Reliability**: Fixed sync process to prevent accidental deletion of PyFulmen source code

**🛡️ Safety Improvements**:

- **Prune Protection**: Set `prune_stale: false` to protect PyFulmen implementation from sync deletion
- **Clean Separation**: No more conflicts between custom code and synced assets
- **Reproducible Builds**: Repository now works on new machines without local Crucible dependency
- **Linting Updates**: Added ruff.toml ignores for Crucible-generated files

#### Technical Details

**Sync Configuration Changes**:

```yaml
# Before: Mixed custom + synced in same directory (dangerous)
src/pyfulmen/foundry/  # Custom implementation + synced exit_codes.py

# After: Clean separation (safe)
src/pyfulmen/foundry/     # Custom implementation only
src/crucible/pyfulmen/     # Crucible-synced assets only
```

**Import Path Changes**:

```python
# PyFulmen now imports from Crucible assets
from crucible.pyfulmen.foundry.exit_codes import ExitCode
```

#### Test Results

- **1674 tests**: 1670 passed, 4 failed (documentation-related only)
- **Core Functionality**: All critical tests pass
- **Build Success**: `make clean`, `make bootstrap`, `make build`, `make prepush` all successful
- **Linting**: All checks pass with proper ignores for generated files

#### Migration Notes

**For Users**: No breaking changes - all PyFulmen APIs remain identical

**For Developers**:

- Crucible assets now in `src/crucible/` (read-only)
- Custom code in `src/pyfulmen/` (safe from sync)
- Use `make sync` to update Crucible assets
- Never edit files in `src/crucible/` directly

### [0.1.12] - Telemetry System Implementation - 2025-11-06

**Release Type**: Major Feature Enhancement - Enterprise Telemetry & Observability
**Release Date**: November 6, 2025
**Status**: ✅ Ready for Release

**Summary**: PyFulmen v0.1.12 delivers comprehensive enterprise telemetry system implementing ADR-0008 with MetricRegistry, Prometheus export, and cross-module instrumentation. This release establishes production-ready observability across all PyFulmen modules with thread-safe metrics collection, performance optimization, and seamless integration patterns.

#### Key Features

**📊 Enterprise Telemetry Infrastructure**:

- Complete `pyfulmen.telemetry` module with MetricRegistry, Counter, Gauge, Histogram instruments
- Thread-safe metrics collection with atomic operations and concurrent access support
- Prometheus exporter with `/metrics` endpoint and comprehensive metric formatting
- **Prometheus Exporter Metrics**: Full Crucible v0.2.7 taxonomy compliance with 7 new metrics
  - `prometheus_exporter_refresh_success_total`, `prometheus_exporter_refresh_errors_total`, `prometheus_exporter_refresh_duration_seconds`
  - `prometheus_exporter_http_requests_total`, `prometheus_exporter_http_errors_total`
  - `prometheus_exporter_inflight_operations`, `prometheus_exporter_restart_total`
  - Dual-emission system with `PYFULMEN_DUAL_EMISSION` environment variable for backward compatibility
  - RefreshContext for automatic operation tracking with proper error classification
- Module-level helpers (`counter()`, `gauge()`, `histogram()`) for zero-complexity usage
- 36 comprehensive tests (26 unit + 10 integration, 100% pass rate)

**🔧 Cross-Module Instrumentation**:

- **Foundry Module**: MIME detection telemetry with operation timing and algorithm-specific metrics
- **Error Handling**: Wrap operation telemetry with performance monitoring
- **FulHash Module**: Algorithm-specific hashing telemetry with byte throughput tracking
- Performance-optimized patterns with <1ms typical overhead
- Import optimization for performance-sensitive modules

**⚡ Progressive Interface Design**:

- Zero-complexity defaults: `counter("name")`, `gauge("name")`, `histogram("name")` work instantly
- Enterprise power-ups: Custom registries, labels, Prometheus export, batch operations
- Thread-safe singleton pattern with automatic cleanup
- Comprehensive error handling and graceful degradation

**🚀 Production-Ready Features**:

- Atomic operations using Python's `threading.Lock()` for thread safety
- Prometheus-compatible metric formatting with proper metadata
- Performance-optimized histogram buckets and efficient event storage
- Memory-efficient event collection with configurable retention

#### Technical Implementation

**Architecture Patterns**:

- Registry pattern with thread-safe metric management
- Atomic operations for concurrent metric updates
- Prometheus text format compliance for ecosystem integration
- Performance-optimized histogram implementations

**Quality Assurance**:

- **278+ Tests**: 259 baseline + 19 new telemetry integration tests (100% pass rate)
- **Performance**: <1ms typical overhead, <10ms worst-case for complex operations
- **Thread Safety**: Validated concurrent access patterns
- **Memory Efficiency**: Optimized event storage and cleanup
- **Crucible Compliance**: Full v0.2.7 taxonomy compliance with proper metric naming and labels

#### Module Integration Details

**Foundry MIME Detection**:

- Metrics: `foundry_mime_detections_total_*`, `foundry_mime_detection_ms_*`
- Algorithm-specific tracking for magic, extension, and fallback detection
- Performance optimization with module-level imports

**Error Handling Operations**:

- Metrics: `error_handling_wraps_total`, `error_handling_wrap_ms`
- Wrap operation timing with comprehensive error tracking
- Integration with existing error handling patterns

**FulHash Algorithm Performance**:

- Metrics: `fulhash_operations_total_*`, `fulhash_bytes_hashed_total`, `fulhash_operation_ms`
- Algorithm-specific tracking for SHA256, BLAKE3, MD5, etc.
- Byte throughput monitoring for performance analysis

#### Documentation & Examples

**Complete API Documentation**:

- Comprehensive module documentation with usage examples
- Integration guides for adding telemetry to new modules
- Performance optimization guidelines and best practices
- Troubleshooting guide for common telemetry scenarios

**Real-World Examples**:

```python
# Basic usage - zero complexity
from pyfulmen.telemetry import counter, gauge, histogram

# Create metrics instantly
ops_counter = counter("operations_total")
memory_gauge = gauge("memory_bytes")
request_duration = histogram("request_duration_ms")

# Use in your code
ops_counter.inc()
memory_gauge.set(1024 * 1024)
request_duration.observe(45.2)
```

**Enterprise Integration**:

```python
# Advanced usage with Prometheus export
from pyfulmen.telemetry import MetricRegistry, PrometheusExporter

registry = MetricRegistry()
exporter = PrometheusExporter(registry)

# Add custom metrics with labels
request_counter = registry.counter("http_requests_total", labels=["method", "status"])
request_counter.labels(method="GET", status="200").inc()

# Export for Prometheus scraping
metrics_text = exporter.export()
```

#### Breaking Changes

- None (fully backward compatible with v0.1.11)

#### Migration Notes

**No migration required** - telemetry system is entirely additive. Existing applications gain observability automatically when using instrumented modules.

**Optional Integration**:

```python
# Applications can optionally collect metrics
from pyfulmen.telemetry import get_global_registry
from pyfulmen import foundry, fulhash

# Use modules normally - they instrument themselves
mime_type = foundry.detect_mime_type("example.txt")
file_hash = fulhash.hash_file("example.txt")

# Retrieve metrics for monitoring/observability
registry = get_global_registry()
events = registry.get_events()
for event in events:
    print(f"{event.name}: {event.value}")
```

#### Quality Gates

- [x] All 268 tests passing (259 baseline + 9 new telemetry integration tests)
- [x] Thread safety validated with concurrent access patterns
- [x] Performance benchmarks meeting enterprise requirements (<1ms overhead)
- [x] Prometheus export compliance verified
- [x] Code quality checks passing (ruff, mypy)
- [x] Documentation complete with examples and integration guides
- [x] Memory efficiency validated with large-scale metric collection
- [x] Cross-module integration tested with Foundry, Error Handling, and FulHash modules

#### Future Enhancements

**Fast-Follow Telemetry Features** (planned for v0.1.13):

- OpenTelemetry export for cloud-native observability
- Custom metric types and advanced histogram configurations
- Metrics aggregation and statistical summaries
- Integration with popular monitoring systems (Grafana, DataDog)
