Oct2026

Overview

The Combinatorics Framework (JVM Edition) is an expressive test-design, generation, and execution workbench designed to turn massive, unmanageable combination spaces into small, executable, and systematically covered test sets. It bridges the gap between static combinatorial models and active test execution, verification, and performance analysis.

Core Architecture & Technical Details

• Self-Contained Execution: Built as a single Java 25 application that provides a command-line interface, a desktop GUI (guif), and an embedding API. It runs without needing Python, a relational database, or external containers at runtime.
• Safety & Sandboxing: Includes resource budgets, deterministic seeds/checkpoints, execution isolation, and options to run Python cases inside sandboxes (bwrap or Docker).
• The Bootstrap (FW_RunMeFirstOnce): Runs once and strictly first for an entire test suite to prepare shared state or check the system under test, passing global arguments via FW_Arguments.

Advanced Modeling & Composition

• Compositional Generators: Supports advanced operations where generated rows become units for subsequent generators, and joins connect structured data to create large experimental spaces from concise inputs.
• Flexible Action Shapes: Models static parameters, ordered action sequences (FW_Permut), group subsets (FW_Subsets_RANGE), repetitions, and sudden/optional events (FW_Optional) that run with and without every kept scenario row.
• Pre-Run Planning: Computes exact combinatorial counts and resource estimates before execution so costs and coverage tradeoffs are fully understood up front.

Constraints, Sieve, and Rules

• Automated Business Rules: Constraints can be defined via JSON or interactive workbench tools using forbid/require pairs, value formulas, and condition gates (all, any, not).
• Preserving Negative Tests: Rules filter out impossible combinations automatically, but allow deliberate negative test configurations to remain so developers can catch structural and state-based defects.

Execution, Verdicts, and Triage

• Named Verdicts: Test cases execute in isolation, recording outcomes and assigning named custom variables (FW_CUSTOM_VAR) to attribute failures directly to the broken rule.
• Automated Triage: Groups finished run failures by what distinguishes them and generates minimal failing witnesses to streamline debugging.

Optimization, Campaigns, and Metrics

• Multi-Objective Tuning: Computes Pareto fronts (exact or via NSGA-II) and provides balanced picks (weighted sum, Tchebycheff, distance to ideal) to evaluate performance metrics like latency, cost, and throughput.
• Iterative Campaigns: Runs scenarios in multiple rounds where successful results bias subsequent iterations while maintaining an exploration floor.
• Coverage Integration: Capable of importing external code coverage reports (such as JaCoCo, coverage.py, and gcov).

Familiarization recommended

• with AI assistant [AI_DELEGATION] is a human-readable instructions (not for training)
• with Systems-Under-Test (SUT) folder content, stored on GitHub's repos of the author. These downloaded folders recommended to be placed with executable jar next to each other

Environment

• Surprise-surprise: requires Java 25
• Python 3.11+ (optionally)

Licensing Terms

• Business Source License 1.1: Includes an Additional Use Grant allowing free use by individual humans (testers, engineers, students) on one active installation for learning, research, and professional practice.
• Restrictions: Shared company infrastructure, product/third-party services inclusion, or automated/AI operation without direct human QA direction are restricted under the license terms.
• Future Transition: The license automatically converts to AGPL-3.0-only on August 8, 2030.