# Development Report

## Objective

The project supplies MoonBit with a reusable, deterministic decision-tree foundation for small and medium in-memory numeric datasets. The implementation was rebuilt for the current MoonBit toolchain rather than publishing the legacy prototype in `CascadeProjects/decision_tree`.

## Implemented Architecture

`data.mbt` owns dataset validation and defensive copying. `classification.mbt` and `regression.mbt` implement separate typed models with deterministic exact split search. The model nodes retain samples, impurity or variance, and gain so later modules can inspect, prune, and export the model without retraining.

`metrics.mbt` contains evaluation definitions. `introspection.mbt` traverses immutable trees. `pruning.mbt` applies a leaf-risk plus alpha-times-leaf-count objective and returns a new model. `validation.mbt` creates non-overlapping folds and trains only from each fold's training indices. `export.mbt` validates names and serializes the retained structure.

`model_selection.mbt` evaluates complete caller-supplied configuration grids. `reports.mbt` builds detailed classification and regression summaries. `explanation.mbt` assigns stable pre-order leaf IDs and extracts structured rules. `diagnostics.mbt` implements deterministic permutation importance and partial dependence. `pruning_path.mbt` derives increasing cost-complexity strengths and retains only distinct smaller models.

`weighted.mbt` implements separately typed sample-weighted datasets and trees, including weighted split scoring, predictions, and metrics. `weighted_introspection.mbt` exposes structural inspection for those models. `advanced_validation.mbt` implements repeated cross-validation summaries and validation-based pruning-strength selection.

## Capability Evidence

| Capability | Public entry points | Main tests |
| --- | --- | --- |
| Dataset validation | `classification_dataset`, `regression_dataset` | `data_test.mbt` |
| Classification | `train_classifier`, `predict`, `predict_proba`, `predict_batch` | `classification_test.mbt` |
| Regression | `train_regressor`, `predict`, `predict_batch` | `regression_test.mbt` |
| Metrics | accuracy, confusion matrix, MSE, MAE, RMSE, R-squared | `metrics_test.mbt` |
| Inspection | depth, counts, paths, feature importance | `introspection_test.mbt` |
| Pruning | classification and regression `prune` | `pruning_test.mbt` |
| Pruning selection | classification and regression `pruning_path` | `pruning_path_test.mbt` |
| Validation | K-fold, stratified K-fold, cross-validation | `validation_test.mbt` |
| Model selection | configuration grids, holdout, candidate selection | `model_selection_test.mbt` |
| Detailed reports | per-class metrics, probability scores, regression diagnostics | `reports_test.mbt` |
| Explanations | leaf IDs, evidence, structured rules | `explanation_test.mbt` |
| Diagnostics | permutation importance, partial dependence | `diagnostics_test.mbt` |
| Export | text, JSON, DOT | `export_test.mbt` |
| Sample weighting | weighted datasets, training, prediction, metrics, inspection | `weighted_test.mbt` |
| Advanced validation | repeated validation and pruning-strength selection | `advanced_validation_test.mbt` |

## Determinism

Feature candidates are visited by ascending feature index. Rows are sorted by feature value with original row index as the secondary key. A candidate replaces the current best only when its gain exceeds the current gain by the documented floating tolerance. Fold ordering is a deterministic cyclic order controlled by the supplied integer seed.

## Validation State

The release commands are listed in `docs/acceptance-checklist.md`. The local verified state has 70 passing tests and five runnable examples. `scripts/source-audit.ps1` provides reproducible line counts and placeholder checks instead of embedding a manually maintained code-size claim.

## Boundaries

Version `0.2.0` does not claim categorical features, missing values, ensembles, persistence import, parallel training, or measured production performance. Those areas can be evaluated in later versions without changing the factual scope of this release.