Release v0.9.0 — Core Freeze - #1
Merged
Merged
Conversation
Initialize the AlphaForge project foundation. Includes: - TypeScript strict configuration - pnpm workspace setup - ESLint configuration - Prettier formatting - Vitest testing environment - GitHub Actions CI workflow - Initial project documentation - Development tooling configuration The repository is now ready for feature development.
Add a GitHub pull request template to standardize contribution workflow. The template provides: - PR description guidance - change summary section - validation checklist - documentation and architecture reminders This improves consistency across future development branches.
Incorporate the complete image loading and normalization feature into the development branch. Includes: - Addition of sharp dependency and build approval - Implementation of image loading utilities with sharp normalization - Comprehensive test coverage for the image loader module - Roadmap documentation update marking image loading as complete - Prettier tooling update to ignore the pull request template This delivers robust input/output image handling capabilities for the AlphaForge project foundation.
Add a comprehensive image validation system including error hierarchy, metadata and dimension validators, orchestration logic, and corresponding test suites. This implementation provides: - Validation error hierarchy for structured error handling - Metadata and dimension validators for image processing - Image validation orchestration logic and exports - Unit and integration tests for validators and orchestration - Updated task tracking in TASKS.md for Milestone 2 This establishes the core validation pipeline for future development.
Introduce new ADR (Architecture Decision Record) and API documentation files, while updating existing documentation across the repository. This update provides: - New ADR.md to track architectural decisions - New API.md specifying interface guidelines and endpoints - Updates to ARCHITECTURE.md, CLAUDE.md, PROJECT.md, and README.md This improves project structure, technical governance, and onboarding clarity.
Add a complete color processing module featuring sRGB and linear RGB conversion, error handling, types, orchestration, test suites, and corresponding documentation updates. This implementation provides: - sRGB and linear RGB color conversion logic - Custom error hierarchy and type definitions for color operations - Main color module entry point and index exports - Comprehensive unit and integration test suites - Updates to ADR.md, API.md, TASKS.md, and core entry points This establishes the color conversion pipeline for future image manipulation tasks.
Introduce formal, RFC-2119-style normative specifications for the alpha reconstruction, foreground reconstruction, cleanup, and validation pipelines, while updating project documentation. This update provides: - Alpha reconstruction, foreground reconstruction, cleanup, and validation specification documents - Mathematical foundations, mandatory behavior, error handling, and deterministic requirements - Updates to PROJECT.md and README.md to reference the new specifications - Progress tracking updates in TASKS.md marking Milestone 4 specification tasks complete This establishes the technical foundation and design guidelines for future implementation phases.
…pelines Update alpha and foreground reconstruction specifications to guarantee numerical stability and prevent mathematical overflows when processing imperfect AI-generated inputs. - Define EPSILON and strict [0.0, 1.0] clamping for alpha reconstruction to prevent division by zero. - Introduce an ALPHA_THRESHOLD (0.01) and a fallback color strategy for foreground recovery to avoid exploding quantization noise. - Mark Milestone 4 technical review as complete in TASKS.md.
…onstruction module Add the core alpha reconstruction module implementing Porter–Duff two-observation models, complete with error handling, strict validation, type definitions, test suites, and documentation updates. This implementation provides: - Porter–Duff two-observation alpha reconstruction core algorithm operating on LinearImageData - Per-channel alpha estimation with epsilon thresholding, unweighted mean aggregation, and strict [0, 1] clamping - Custom AlphaReconstructionError hierarchy and robust input validation (dimensions, formats, buffer sizes) - Full TDD test suite (21 tests) and deterministic test utilities - Public API exports, API documentation update, and Milestone 5 completion in TASKS.md
Implement the complete foreground reconstruction stage.
The module recovers the original linear RGB foreground color from a single
observed composite image, a known background color, and a reconstructed
alpha channel using the inverse Porter–Duff equation:
F = (C - (1 - α)B) / α
For pixels where α < 0.01 (ALPHA_THRESHOLD), the output is the deterministic
neutral fallback (0, 0, 0). All recovered color channels are strictly
clamped to the physical range [0, 1].
What this commit includes:
- ForegroundImageData: immutable 3-channel linear RGB container
- ForegroundReconstructionError: typed error for all failure modes
- reconstructForeground(): pure, deterministic, validated implementation
- Comprehensive TDD test suite (23 tests)
- Public API exports and API.md registration
- Milestone 6 completion in TASKS.md
- Verification of public exports in tests/index.test.ts
The module remains independent of Cleanup, PNG Export, CLI, and pipeline
orchestration. It consumes only AlphaChannelData and produces only
ForegroundImageData, preserving the project's dependency direction.
Implement the complete cleanup pipeline stage, featuring alpha thresholding, connected-component noise removal, and grayscale morphology (erosion and dilation) with multiple structuring elements. The pipeline executes in a strict, fixed order: thresholding, noise removal, and morphology (opening followed by closing). It guarantees mathematical determinism and input immutability, processing alpha channels while validating and preserving optional foreground image data. What this commit includes: - Core pipeline orchestrator (`cleanup()`) and typed `CleanupError` hierarchy - Grayscale morphological operations supporting square, disk, and cross shapes - Connected-component analysis for noise removal with 4- and 8-connectivity - Comprehensive unit, integration, and property-based test suites (70+ tests) - Integration of `fast-check` dev dependency for property-based invariance testing - Public API surface exports and full registration in API.md
Formalize the project's property-based testing strategy across all architectural governance documentation, transitioning it from an ad-hoc practice to a permanent verification standard. This update establishes formal guidelines for ensuring that mathematical algorithms explicitly prove their invariants using property-based verification. What this commit includes: - Added ADR-010 (Verification Strategy Using Property-Based Testing) as an accepted decision - Added Article XX (Verification Through Properties) to CONSTITUTION.md - Introduced a new Verification Architecture section in ARCHITECTURE.md detailing common invariants and constraints - Documented testing layers (Unit, Integration, Property-Based) inside CLAUDE.md for AI coding agents - Appended a minimal Testing Philosophy subsection under the Development section in README.md This update aligns existing fast-check usage with formal project governance, ensuring explicit correctness guarantees for future contributors.
Implements Milestone 8 PNG export support. Includes: - PNG export architecture - PNG export specification - PNG exporter implementation - deterministic RGBA8 encoding - linear RGB to sRGB conversion reuse - export validation - ExportError handling - unit tests - property-based tests - integration tests This milestone introduces the final export stage required to transform reconstructed linear image data into production-ready RGBA8 PNG files.
…arness Introduce an end-to-end experimental validation workflow under a new examples directory to verify pipeline orchestration, mathematical precision, and output correctness against controlled synthetic assets. This harness runs exclusively against the public API surface (`reconstructAlpha`, `reconstructForeground`, and `cleanup`), confirming API stability and readiness for CLI development without modifying production source code. What this commit includes: - `generate-synthetic.mjs`: controlled test asset generator producing ground-truth reference and dual-observation (black/white) images with varied transparency profiles - `reconstruct.mjs`: experimental validation runner supporting configurable backgrounds, optional multi-stage cleanup parameters, debug asset exports, and quantitative error metrics (MAE, Max Error) - Quantitative confirmation of alpha precision (MAE < 1.02e-4 without cleanup) and structural integrity of exported transparent PNGs - Local `.gitignore` to isolate generated verification assets and prevent PNG artifacts from tracking - Comprehensive markdown guide in `README.md` detailing the execution and validation procedures
…erty-based verification Introduce a dedicated pipeline orchestration module (`src/pipeline/`) to sequence the entire reconstruction workflow and add property-based testing across color and reconstruction layers to fulfill ADR-010 requirements. The new orchestration layer handles execution sequencing exclusively: loading images, validating dimensions, converting color spaces, calculating alpha/foreground data, and conditionally invoking cleanup operations. This maintains high separation of concerns without duplicating underlying algorithmic logic. What this commit includes: - Unified `reconstructPipeline()` engine and structured `PipelineError` container - Updated architectural dependency models and public boundary specifications in ARCHITECTURE.md and API.md - Pipeline integration test suite ensuring correct execution, multi-stage cleanup, and immutability - Comprehensive property-based test suites using `fast-check` for color processing, alpha reconstruction, and foreground reconstruction modules - Global public exports routed through the primary package index (`src/index.ts`)
…ervations Implement dual-observation foreground reconstruction to eliminate output differences caused by observation ordering. Previously, foreground reconstruction relied only on the first observation/background pair, causing recovered foreground colors and exported assets to depend on which image was provided as observation A. This change makes the reconstruction pipeline mathematically symmetric by recovering foreground estimates from both observations and combining them into a deterministic final foreground representation. Changes: - Replace single-observation foreground recovery with dual-observation input model. - Recover foreground independently from both composite observations. - Average both foreground estimations to reduce quantization artifacts. - Update pipeline orchestration to provide both observations equally. - Update foreground reconstruction types and public API documentation. - Update reconstruction specifications to document order invariance guarantees. - Update example reconstruction harness for the new API contract. - Add regression tests validating observation swap invariance. - Add property-based tests covering symmetric foreground reconstruction. - Extend pipeline/export integration tests to verify identical output ordering. Behavioral guarantees: - Swapping observation A/B with their corresponding backgrounds produces identical alpha reconstruction. - Swapping observation A/B does not affect the recovered foreground. - Exported PNG output remains deterministic regardless of input ordering. Technical notes: - Alpha reconstruction equations remain unchanged. - Porter-Duff reconstruction model remains unchanged. - The mathematical core continues to operate without ML, segmentation, or heuristic inference. Tests: - pnpm run lint - pnpm run typecheck - pnpm run test - pnpm run build - pnpm run format:check Refs: - Milestone 8.5.1 — Order-invariance reconstruction hardening - ADR-009 — Linear RGB processing pipeline
Introduce an optional validation layer to detect inconsistencies between declared background colors and the actual image border colors before reconstruction starts. This milestone addresses real-world failures caused by AI-generated assets where visually identical backgrounds frequently contain small RGB deviations from the declared values, producing alpha reconstruction artifacts and foreground contamination. Changes: - Add deterministic border sampling background measurement. - Measure background colors in linear RGB space using existing color pipeline. - Add configurable background mismatch validation with variance metadata. - Introduce BackgroundMismatchError with detailed diagnostic context. - Integrate optional validation into reconstructPipeline. - Keep reconstruction mathematics unchanged. - Preserve backwards compatibility when validation is disabled. - Export new validation utilities through the public API. - Add documentation and ADR describing validation-before-inference strategy. - Add unit, integration, and property-based tests. Behavioral guarantees: - Explicit background validation prevents silent reconstruction artifacts. - Incorrect background declarations fail deterministically. - Existing reconstruction behavior remains unchanged when validation is omitted. - Validation does not introduce ML, segmentation, or heuristic inference. Tests: - pnpm run lint - pnpm run typecheck - pnpm run test - pnpm run build - pnpm run format:check Refs: - Milestone 8.5.2 - ADR-012
…arness Add CLI support for validating declared background colors before reconstruction. Changes: - Add --validate-background, --background-border-width and --background-threshold flags. - Integrate BackgroundMismatchError validation into the example runner. - Document background validation usage and mismatch scenarios. Verification: - pnpm lint - pnpm typecheck - pnpm test - pnpm build
- Add ADR-013 documenting the Core Freeze decision - Add Article XXI to CONSTITUTION.md for the immutable mathematical core - Create CHANGELOG.md with the initial Unreleased entry - Update PROJECT.md, README.md, and TASKS.md to reflect the Core Freeze phase - Document the Validation→Color Science dependency in ARCHITECTURE.md - Introduce a future optional Refinement extension point - Add an explicit error contract to API.md, including PipelineError.cause - Standardize all five pipeline specifications as Stable 1.0.0 - Remove obsolete branch references, change log sections, and implementation notes - Move background color mismatch validation into current validation requirements Files affected: - ADR.md - API.md - ARCHITECTURE.md - CHANGELOG.md (new) - CONSTITUTION.md - PROJECT.md - README.md - TASKS.md - docs/specifications/alpha-reconstruction.md - docs/specifications/cleanup.md - docs/specifications/foreground-reconstruction.md - docs/specifications/png-export.md - docs/specifications/validation.md No functional or API behavior changes were introduced.
Promote ReconstructPipelineCleanupOptions to public API, keep ColorConversionError internal, remove Math.random from color tests, add reconstructAlpha order-invariance property test, and move background inference tasks to Milestone 8.7. Files Affected: - API.md - TASKS.md - src/index.ts - tests/index.test.ts - tests/utils/random.ts - tests/reconstruction/helpers.ts - tests/color/color-converter.test.ts - tests/reconstruction/alpha-reconstruction-properties.test.ts
Officially completes Milestone 8.6 — Core Stabilization / Core Freeze. This integration delivers: - Declaration of the AlphaForge Core as frozen - Public API freeze documented in API.md and ADR-014 - Updated governance documentation across PROJECT.md, README.md, TASKS.md, and CHANGELOG.md - Addition of ADR-014: Public API Freeze - No functional, algorithmic, or API signature changes Files changed: - ADR.md - CHANGELOG.md - PROJECT.md - README.md - TASKS.md No source code behavior was modified. All verification passes: - pnpm test: 265 tests passed - pnpm typecheck: clean - pnpm lint: clean
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
AlphaForge v0.9.0 — Core Freeze Release
This pull request prepares the first public release of AlphaForge.
Summary
This release completes the Core Freeze milestone.
The following areas are now considered stable:
Release Preparation
This PR includes:
Verification
The release branch has been validated with:
✅ pnpm build
✅ pnpm typecheck
✅ pnpm lint
✅ pnpm test (265 tests passing)
✅ npm pack --dry-run
Scope
No changes were made to:
Future improvements such as background inference, refinement filters, and visual enhancements will be implemented as optional layers outside the frozen core.
Release Process
After merge:
v0.9.0