Changelog

View Source

All notable changes to the Framework will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.5.0] - 2025-10-21

🔧 Package Configuration - Public Hex.pm Release

  • IMPORTANT: Changed from private organization to public Hex.pm package
    • ✅ Removed: organization: "makerstudio" from package configuration
    • ✅ Updated: All documentation to reflect public package usage
    • ✅ Migration: Users can now install via {:framework, "~> 0.5.0"} (no organization needed)
    • This makes the framework publicly accessible to the entire Elixir community

🌍 Internationalization (i18n) - Complete Framework-Level Support

  • MAJOR FEATURE: Full i18n support integrated into the framework's canonical flow

    • ✅ Locale Resolution: Multi-layered priority chain (input → user → session → header → default)
    • ✅ Context Integration: Framework.Kernel automatically hydrates ctx.locale for all operations
    • ✅ Pure Translation Helpers: t/3 and tn/5 available in plan functions (no I/O, deterministic)
    • ✅ Effects Locale Support: Email/webhook templates automatically resolve locale-specific versions
    • ✅ Template Fallback: Graceful degradation from locale-specific → default templates
    • ✅ Gettext Integration: Compile-time translation validation with .po file support
    • ✅ 3 Default Locales: en-US, es-ES, fr-FR included with framework
    • ✅ Documentation: Complete examples in moduledocs and building-b2b-app-using-framework.md
    • ✅ 23 New Tests: Full coverage of locale resolution, translation, and template systems
    • ✅ All 297 Tests Passing: Zero regressions, full backward compatibility

  • New Modules:

  • Enhanced Modules:

  • New Files:

    • priv/gettext/{en-US,es-ES,fr-FR}/LC_MESSAGES/*.po - Translation files
    • priv/email_templates/{en-US,es-ES,fr-FR}/*.txt - Locale-specific email templates

  • Configuration:

    config :framework, Framework.I18n,
  default_locale: "en-US",
  supported_locales: ["en-US", "es-ES", "fr-FR"],
  gettext_backend: MyApp.Gettext

  • Migration Path: Products can immediately start using i18n by:

    1. Configuring supported locales
    2. Using t(ctx, key) in plan functions for translations
    3. Creating locale-specific templates in priv/{email,webhook}_templates/{locale}/
    4. Extracting translation keys with mix gettext.extract

[0.4.12] - 2025-10-02

🔧 Code Quality - Dialyzer Type Checking Fix

  • IMPROVEMENT: Eliminated Dialyzer warning in Framework.Effects.Email module
    • ✅ Root Cause: Runtime defmodule TempMailer inside function blocked static analysis
    • ✅ Solution: Replaced dynamic module creation with direct Swoosh adapter invocation
    • ✅ Impact: Full Dialyzer type verification now covers email delivery path
    • ✅ Performance: Eliminated unnecessary module creation overhead on every email send
    • ✅ Verification: All 276 tests pass, Dialyzer passes cleanly, zero regressions
    • Enhanced type safety enables better compile-time error detection

📚 Documentation Quality - Comprehensive Spec & Doc Audit

  • VERIFIED: Complete audit of all @spec, @type, and @doc examples
    • ✅ All 9 @spec declarations verified correct and matching implementations
    • ✅ All 2 @type definitions verified used correctly in specs
    • ✅ All 272 @doc/@moduledoc blocks comprehensive and accurate
    • ✅ All 2 doctests passing with runnable examples
    • ✅ Zero @deprecated annotations (all code current)
    • Framework maintains 100% documentation quality score

[0.4.11] - 2025-10-02

🚀 Transaction DSL Effects System

  • FEATURE: Complete Framework.Transaction.DSL effects system implementation
    • Transaction context piping and effect idempotency handling
    • Comprehensive test coverage for transaction flows
    • Enhanced runtime environment handling with fallback to configuration

[0.4.10] - 2025-09-03

🔧 Process Improvement - Publish Script Reliability

  • IMPROVEMENT: Enhanced publish script timeout handling to prevent build interruptions
  • Infrastructure: Extended timeout capacity for comprehensive CI/CD pipeline completion
  • Quality Assurance: Full static analysis and documentation generation now completes reliably

[0.4.9] - 2025-09-03

🚨 Critical Bug Fix - SLO Monitoring Negative Emit Lag

  • CRITICAL FIX: Fixed negative emit lag times causing Framework's SLO monitoring system gauge updates to fail
    • ✅ Root Cause: Clock skew between database and application servers caused DateTime.diff() to return negative values when database timestamps were in the future
    • ✅ Solution: Added max(0, ...) wrapper to ensure emit_lag_ms() and consumer_lag_ms() always return non-negative values
    • ✅ Impact: OpenTelemetry gauge updates no longer fail, preventing SLO monitoring system shutdown
    • ✅ Verification: All 71 framework tests pass, 8 observability tests pass, clock skew scenarios handled correctly
    • The fix gracefully handles clock synchronization issues between database and application infrastructure

🔧 Technical Details

  • Enhanced StreamEmitter.emit_lag_ms/0: Now prevents negative lag values using max(0, DateTime.diff(now, created_at_utc, :millisecond))
  • Enhanced StreamEmitter.consumer_lag_ms/1: Same protection applied to consumer lag calculations
  • Clock Skew Resilience: Framework now tolerates database server clocks running ahead of application servers
  • Zero Breaking Changes: Existing API contracts maintained, all observability metrics continue to work correctly

[0.4.8] - 2025-09-03

🚨 Critical Bug Fix - Primary Key Upsert Operations

  • CRITICAL FIX: Fixed primary key exclusion in Framework upsert operations that caused PostgreSQL NULL constraint violations
    • ✅ Root Cause: Framework.Kernel.execute_upsert_multi/2 excluded primary key fields from INSERT statements
    • ✅ Solution: Implemented Primary Key Preservation Pattern - extract primary keys before changeset filtering, validate via changeset, then merge back for database operation
    • ✅ Security Maintained: Schema changesets still filter primary keys during validation phase
    • ✅ Validation Preserved: All existing validation rules execute normally
    • ✅ Architecture Clean: Fix contained in kernel layer, no schema changes required
    • ✅ Impact: ALL Framework upsert operations with explicit primary keys now work correctly
    • The fix preserves validation and security boundaries while ensuring primary keys reach PostgreSQL
    • All 241 tests pass with enhanced upsert reliability

🔧 Technical Details

  • Enhanced execute_upsert_multi/2: Now uses Primary Key Preservation Pattern
  • Validation First: Changesets validate all fields except primary keys (security preserved)
  • Merge Strategy: Primary keys merged back into changeset.changes only after validation passes
  • Database Operation: Enhanced changeset with primary keys sent to PostgreSQL
  • Zero Breaking Changes: Existing API contracts maintained

[0.4.6] - 2025-09-03

🚨 Critical Bug Fixes - Sequence Management Race Condition

  • SECURITY FIX: Eliminated race condition in sequence management by leveraging PostgreSQL BIGSERIAL atomicity
    • ✅ Removed manual nextval() calls: Framework now uses INSERT...RETURNING sequence for atomic sequence generation
    • ✅ Fixed race conditions: Sequence generation is now atomic within transaction boundaries
    • ✅ Guaranteed ordering: Events are now in true commit order without gaps from rollbacks
    • ✅ Better performance: Eliminated separate sequence calls, reduced I/O operations
    • The previous approach of manual nextval('outbox_sequence_seq') outside INSERT broke atomicity
    • This could cause sequence gaps and out-of-order events in high-concurrency scenarios
    • All 241 tests pass with enhanced reliability and no sequence management race conditions

🔧 Internal Changes

  • Updated insert_event!/3: Now returns atomically generated sequence from PostgreSQL
  • Refactored transaction flows: Event generation now drives sequence allocation atomically
  • Fixed JSONB handling: Let PostgreSQL handle JSONB conversion instead of pre-encoding
  • Updated test helpers: Removed manual sequence management from test utilities

[0.4.5] - 2025-09-03

✨ Enhanced Architecture & Performance

  • Configurable Effects Worker: Made effects worker configurable and removed hardcoded dependency
    • Framework no longer assumes specific worker configuration
    • Better separation of concerns between framework and application
    • Enhanced flexibility for different deployment scenarios

[0.4.4] - 2025-09-02

✨ Enhanced Architecture & Performance

  • Configurable Upsert Conflict Resolution: Removed hardcoded upsert logic from Framework.Kernel.execute_upsert

    • Added conflict_resolution_registry configuration for table-specific conflict strategies
    • Supports :replace_all, {:replace, field_list}, and custom strategies per table
    • Eliminates framework coupling to specific business schema requirements
    • Enhanced flexibility for different application domain needs

  • Ecto.Multi Transaction Handling: Upgraded transaction processing for improved atomicity

    • Transaction DSL plans now use Ecto.Multi for atomic multi-step operations
    • Better error isolation and rollback semantics
    • Enhanced debugging and transaction failure reporting
    • Improved performance through optimized transaction pipelines
    • All 241 tests pass with enhanced transaction reliability

🔧 Configuration Changes

  • New Config: Added conflict_resolution_registry to framework configuration
    • Maps table names to upsert conflict resolution strategies
    • Backwards compatible - defaults to :replace_all for unconfigured tables
    • Example: conflict_resolution_registry: %{users: {:replace, [:email, :name]}}

[0.4.3] - 2025-09-02

🔧 Bug Fixes

[0.4.2] - 2025-01-01

🚨 Critical Bug Fixes - COMPLETE FIX

  • SECURITY FIX: Fixed ALL validation failure patterns in Framework.Kernel.compile
    • ✅ Return-based failures: %{type: :fail, error: :validation_failed, ...} now properly return {:error, {error_type, reason}}
    • ✅ ensure() calls: ensure(condition) inside plan functions now properly return {:error, {error_type, reason}}
    • ✅ Exception-based: Direct DSL ensure() calls continue to work correctly
    • This prevents data corruption and business logic constraint violations
    • All 241 tests pass with no regressions

[0.4.1] - 2025-01-01 [YANKED - Incomplete Fix]

🚨 Partial Bug Fixes

  • INCOMPLETE: Only fixed return-based validation failures, missed ensure() calls in plan functions

[0.2.0] - 2025-08-29

Added

  • bounded_list/3 Function: New safer alternative to list/2 requiring limit, order_by, and index_hint parameters
  • RequireBoundedList Credo Rule: Compile-time detection of unbounded list/2 calls with helpful guidance messages
  • Migration Generator: New mix framework.gen.migrations task with version stamping and drift detection
  • Invariant Pattern Documentation: Three concrete recipes for unique indexes, guard row locking, and aggregate caps
  • Auth Defense-in-Depth: Database-level enforcement patterns with CI checklist for RLS, FK constraints, and enums
  • Enhanced Effects Idempotency: Clear policy guidance preferring {:by_natural_key, ...} over {:by_request}
  • External Dedupe Recommendations: HTTP semantics documentation for 409 vs 200 response patterns

Enhanced

  • Transaction DSL Documentation: Fixed contradictions, added bounded_list/3 usage examples with safety constraints
  • Effects Documentation: Tightened idempotency guidance with concrete examples and external API recommendations
  • AppSpec Documentation: Added comprehensive multi-layer security patterns with SQL examples
  • Getting Started Guide: Updated to use automated migration generator instead of manual file copying
  • CLAUDE.md: Reflects new automated workflow and enhanced safety features

Security

  • Compile-Time Safety: Prevents unbounded database queries that could cause production outages
  • Database Constraints: Comprehensive patterns for multi-layer authorization enforcement
  • Drift Prevention: Version-stamped migrations with checksum validation prevent configuration drift

Testing

  • Comprehensive Test Coverage: 18 new behavioral tests for bounded_list/3 functionality and Credo rule detection
  • Test Suite Status: 231/231 tests passing (100% success rate) with 0 Credo violations across 82 files

Breaking Changes

  • None - all changes are backward compatible additions

[0.1.3] - 2025-08-29

Added

  • CLAUDE.md: Comprehensive development guide for Claude Code integration
  • Git Repository: Initialized version control with comprehensive .gitignore
  • Development Documentation: Complete architecture overview and workflow patterns
  • Publishing Pipeline: Ready for private Hex.pm distribution

Improved

  • Enhanced .gitignore with Elixir-specific patterns and security considerations
  • Structured project for optimal Claude Code development experience

[0.1.1] - 2025-08-28

Fixed

  • CRITICAL SUCCESS: Achieved 100% test success (134 tests, 0 failures)
  • Fixed foreign key constraint error in UpdateProfile operation user-profile relationship
  • Corrected User schema changeset to support manual ID assignment for test operations
  • Fixed result type mismatch in UserSignup operation for proper DLQ testing
  • Enhanced test schema compatibility with operation requirements
  • Resolved all framework extraction issues from umbrella project structure

Improved

  • Zero Shortcuts Approach: Systematic root-cause analysis and comprehensive fixes
  • Complete architectural compliance maintained throughout all fixes
  • Enhanced schema-operation integration for seamless test execution

[0.1.0] - 2024-08-28

Added

  • Initial release of the Framework
  • Transaction DSL for pure, deterministic operations
  • AppSpec for verified routes and message security
  • Real-time navigation with :navigated → :render supersedence
  • Comprehensive observability with structured logging and metrics
  • Effects system with post-commit, at-least-once execution
  • Event-driven architecture with global sequencing
  • JSON Schema-based contracts with append-only evolution
  • Complete test suite with 151 passing tests
  • Production-ready conformance demo application
  • CI gates for schema validation and architectural compliance

Features

  • Accept → Plan → Commit → Emit → Replay flow: Complete event-driven architecture
  • Pure Transaction DSL: READ → GUARD → COMPUTE → WRITE pattern with compile-time safety
  • Verified Routes & MessageSecurity: Type-safe navigation with pure authorization predicates
  • Global Event Sequencing: Monotonic sequence numbers for total ordering across domains
  • Post-commit Effects: Idempotent external interactions with automatic retry and dead-letter handling
  • Schema Registry: JSON Schema validation with digest verification and PII/size budgets
  • Observability: Structured logging, OpenTelemetry integration, and comprehensive debug overlay
  • Database Integration: Ecto-based with natural-key upserts and foreign key constraint management