# PyFulmen v0.1.9 Release Notes

**Release Date**: November 4, 2025
**Type**: Major Feature Enhancement & Infrastructure
**Status**: ✅ Ready for Release

## Overview

PyFulmen v0.1.9 delivers three major enhancements: comprehensive schema export functionality, standardized exit codes integration, and Crucible v0.2.4 sync with schema migration and app-identity module. This release significantly expands PyFulmen's capabilities for schema management, error handling standardization, and ecosystem configuration while maintaining full backward compatibility.

## Highlights

### 📤 Schema Export API

**Complete Schema Materialization System**:

- **Core API**: `export_schema()` function with JSON/YAML format support and provenance metadata
- **CLI Integration**: `pyfulmen schema export` command with comprehensive options
- **Provenance Tracking**: Automatic metadata embedding with source attribution
- **Validation**: Schema validation before export with detailed error reporting
- **Test Coverage**: 23 comprehensive tests (14 unit + 9 integration, 100% pass rate)

### 🚨 Standardized Exit Codes

**Enterprise Error Handling**:

- **54 Semantic Exit Codes**: Across 11 categories (standard, networking, configuration, runtime, usage, permissions, data, security, observability, testing, signals)
- **Simplified Mode Mappings**: For monitoring/alerting systems integration
- **Cross-Language Consistency**: Aligned with gofulmen/tsfulmen exit codes
- **Comprehensive APIs**: 8 exported functions for exit code management
- **Test Coverage**: 13 parity tests ensuring ecosystem consistency

### 🔧 Crucible v0.2.4 Infrastructure

**Schema Migration & New Modules**:

- **Draft Migration**: JSON Schema draft-07 → 2020-12 across all schemas
- **App-Identity Module**: New repository configuration module for application identity management
- **Additional Standards**: Server management, web styling, protocol standards
- **Provenance Updates**: Latest sync metadata and source attribution

## What's New

### Added

- **Schema Export Module** (`pyfulmen.schema.export`):
  - `export_schema()` - Core export function with format selection (JSON/YAML)
  - Provenance metadata inclusion with configurable options
  - Schema validation and error handling
  - Safe file operations with overwrite protection

- **Schema CLI Integration** (`pyfulmen schema export`):
  - Argparse and Click framework integration
  - Comprehensive command-line options (--format, --output, --no-provenance, --force)
  - Help documentation and error messages
  - Integration with existing schema catalog

- **Exit Codes Module** (`pyfulmen.foundry.exit_codes`):
  - `ExitCode` IntEnum with 54 standardized codes (1246 lines generated)
  - `SimplifiedMode` enum for monitoring system integration
  - 8 exported APIs: ExitCode, SimplifiedMode, version info, metadata access
  - Cross-language parity with gofulmen/tsfulmen

- **App-Identity Configuration Module**:
  - Repository application identity schemas and validation
  - Example configurations and test fixtures
  - Integration with three-layer config system

- **Additional Crucible Standards**:
  - Server management configuration schemas
  - Web styling and branding standards
  - Protocol standards (HTTP REST, gRPC)
  - Code generation templates

### Changed

- **Schema Standards**: Migration from JSON Schema draft-07 to 2020-12
- **Crucible Sync**: Updated to v0.2.4 with comprehensive standards update
- **Documentation**: Updated README with schema export and exit codes sections
- **Dependencies**: Updated to align with Crucible v0.2.4 requirements

### Fixed

- Schema validation compatibility with JSON Schema 2020-12 draft
- Exit code standardization across Fulmen ecosystem

## Breaking Changes

None - fully backward compatible with v0.1.8.

## Quality Metrics

- ✅ **1343 tests passing** (1322 passed, 21 skipped)
- ✅ **93% code coverage** maintained
- ✅ **Schema export functionality** fully tested
- ✅ **Crucible sync validated** and committed
- ✅ **Documentation updated** with examples

## Usage Examples

### Schema Export API

```python
from pyfulmen.schema import export_schema

# Export a schema to JSON
schema_data = export_schema("foundry/v1.0.0/mime-types", format="json")

# Export with YAML format
schema_yaml = export_schema("config/logging/v1.0.0/policy", format="yaml")
```

### CLI Usage

```bash
# Export schema to JSON file
pyfulmen schema export foundry/v1.0.0/mime-types --format json --output mime-types.json

# Export to YAML with provenance
pyfulmen schema export config/logging/v1.0.0/policy --format yaml --include-provenance
```

## Upgrade Guide

### From v0.1.8

```bash
# Using pip
pip install --upgrade pyfulmen

# Using uv
uv pip install --upgrade pyfulmen
```

**No code changes required** - all changes are additive.

## Contributors

- PyFulmen Architect (@pyfulmen-architect)
- Dave Thompson (@3leapsdave)

## References

- [CHANGELOG](../../CHANGELOG.md#019---2025-11-04)
- [Schema Export Documentation](../../README.md#schema-export)
- [Crucible v0.2.4](https://github.com/fulmenhq/crucible/releases/tag/v0.2.4)

---

**Full Changelog**: [v0.1.8...v0.1.9](https://github.com/fulmenhq/pyfulmen/compare/v0.1.8...v0.1.9)
