vital_solver 0.11.3

Pure-Dart nutritional solver. Coordinate-descent optimizer with quality rules (V22b sweet-batch cascade, fruit/fat/carb bounds, whey rescue) and pre-solve report aggregation. No Firebase, no FlutterFl [...]

vital_solver

Pure-Dart nutritional solver for the VITAL FlutterFlow app — extracted from 4 monolithic FlutterFlow custom code entities (applyQualityRulesBeforeSolver, macroOptimizerPQDynamicMaxAction, solveSingleMealWithTargets, buildRecipeCreationPreSolveReport) into a portable, testable library.

Status

🚧 Work in progress — currently in Phase 1 (bootstrap). See the migration plan at ~/.claude/plans/ok-maintenant-explique-moi-serene-firefly.md.

Phase	Status
0 — Snapshot regression harness	✅ done (9 fixtures)
1 — Package skeleton	✅ done
2 — Helpers + portable types	✅ done (115 tests)
3 — Migration applyQualityRulesBeforeSolver	✅ done (203 tests, byte-equivalent legacy)
4 — Migration macroOptimizerPQDynamicMaxAction	✅ done (212 tests, byte-equivalent legacy)
5 — Pipeline + report	✅ done (232 tests, solvePipeline + buildPreSolveReport)
6 — Shims FlutterFlow	✅ artifacts ready (3-stage DSL + migration guide + shim refs); deploy gated on Phase 7
7 — Package publishable	✅ done (v0.7.0, LICENSE, example, dry-run clean); hosting decision pending (see PUBLISHING.md)
8 — Suppression legacy	covered by Phase 6 Stage C cleanup

Goals

1. Unblock SDK push — splitting 370KB of custom code into portable Dart so each FlutterFlow entity drops below the 64KB server limit.
2. Enable automated tests — pure Dart logic is testable via dart test, unlike monolithic custom code closures.
3. Eliminate duplication — ~13% of legacy code is duplicated helpers; centralized here.
4. Decouple from FlutterFlow / Firestore — no DocumentReference, no FieldValue, no FF-specific types in the package surface.

Architecture

lib/
├── vital_solver.dart             ← public API exports
└── src/
    ├── types/                    ← portable types (no Firestore)
    ├── helpers/                  ← toD, asMap, norm, macros (per100g)
    ├── quality/                  ← apply_quality_rules + sub-modules
    ├── optimizer/                ← coordinate descent + rescue passes
    ├── pipeline/                 ← orchestrators
    └── reporting/                ← pre-solve report (warnings, blocking, suggestions)

test/
├── snapshots/                    ← real Firestore cases (Phase 0)
├── legacy/                       ← frozen copies of FF functions (regression baseline)
├── snapshot_regression_test.dart ← compares package output vs legacy
├── sweet_batch_v22b_test.dart    ← V22b cascade scenarios
├── helpers_test.dart
├── quality_test.dart
├── optimizer_test.dart
└── pipeline_test.dart

Usage (target API, Phase 5+)

import 'package:vital_solver/vital_solver.dart';

final output = solveSingleMeal(
  ingredients: [/* IngredientInput list from your data layer */],
  targets: SolverTargets(p: 52, c: 35, l: 17, fiMin: 8),
  context: RecipeContext.standard(),
);

if (output.constraintsOk) {
  // output.gramsById, output.totals, output.diagnostics
} else {
  // Inspect output.errors and output.diagnostics for guidance
}

Development

dart pub get
dart analyze
dart test

License

Private — internal use only for VITAL.