VE Region Builder

VE Region Builder is a standalone R project for creating region-specific VisionEval model folders from a statewide VisionEval template model and a user supplied folder of Virginia statewide CSV inputs prepared for this workflow.

The workflow is non-destructive. It does not modify VisionEval source code, the template model, or the Virginia statewide CSV input folder. Generated models, reports, and logs are written under outputs/.

Workflow Overview

prepare Virginia statewide CSV input folder -> assemble statewide source model -> build regional model -> configure VisionEval runtime -> run generated region

The repository contains code, metadata, and example configs. It does not ship the Virginia source data, template VisionEval models, or generated results.

The Greater Richmond example has been tested end to end with the prepared Virginia statewide CSV input workflow. Other regions should use the same preparation, assembly, build, and run sequence and may reveal additional source-data issues.

Before You Start

Have these items available:

• A VisionEval template model folder
• A Virginia statewide CSV input folder
• The regional build manifest that matches the statewide input package
• A VisionEval runtime installation compatible with the R version used to run models
• A local clone of this repository

Requirements

Install R and the RegionBuilder support packages. The conservative package management path is documented in docs/runtime/r_package_management.md.

Check package status:

Rscript R/runtime/check_packages.R

Install missing required packages into the user-local RegionBuilder library:

Rscript R/runtime/install_packages.R --lib="$env:LOCALAPPDATA\VERegionBuilder\runtime\R-library"

Install packages into the same R version you will use for RegionBuilder and VisionEval. If your VisionEval runtime requires R 4.4.2, run the package management scripts with that R 4.4.2 Rscript.exe.

Run commands from the repository root.

Repository Layout

R/                         Reusable R functions
scripts/                   Command-line entry points
configs/                   Example configs to copy before editing
metadata/                  Input manifest and mapping metadata
data_sources/filelist.txt  Expected statewide input file list
tests/fixtures/            Small fixture model for smoke testing
outputs/                   Generated outputs; ignored by git

For a current maintainer map, see docs/repo/repo_navigation.md. Some generated folders under outputs/ are currently required workflow state even though outputs/ is ignored; see docs/repo/current_generated_state_contract.md before cleanup or reorganization.

Product v0 Planning

The current command-line workflow remains the supported path. Early structure for a Windows-friendly internal product has been added for future installer, runtime detection, and Shiny GUI work:

installer/                 Inno Setup and first-run command-wrapper skeletons
R/runtime/                 R and VisionEval runtime detection/config skeletons
R/gui/                     Placeholder for Shiny GUI v0
docs/                      Product, installer, runtime, GUI, and VA input contracts

See:

• docs/product/product_architecture_v0.md
• docs/product/product_architecture_next_phase.md
• docs/product/product_state_and_data_flow_design.md
• docs/setup/installer_permissions_contract.md
• docs/runtime/runtime_environment_contract.md
• docs/runtime/runtime_diagnostics_v0.md
• docs/runtime/r_package_management.md
• docs/workflow/shiny_gui_v0_workflow.md
• docs/workflow/project_paths_preflight_v0.md
• docs/input_contracts/va_input_standardization_preflight_v0.md
• docs/input_contracts/va_input_standardization_execution_v0.md
• docs/input_contracts/va_input_standardization_contract.md
• docs/input_contracts/statewide_assembly_standardized_inputs_v0.md
• docs/region_build/region_build_from_statewide_v0.md
• docs/workflow/azone_first_regionbuilder_doctrine.md
• docs/region_build/azone_first_region_preflight_v0.md
• docs/workflow/modeler_decision_layer_v0.md
• docs/workflow/modeler_decision_registry_v1.md
• docs/input_contracts/marea_transit_input_contracts_v0.md
• docs/region_build/custom_marea_aggregation_preflight_v0.md
• docs/region_build/custom_marea_region_build_prototype_v0.md
• docs/runtime/custom_marea_visioneval_preflight_v0.md

For Azone-first workflows, use the statewide model assembled from standardized inputs so defs/geo.csv includes metadata-backed geography repairs. Source inputs and older generated model folders are not patched in place. The Shiny prototype saves the latest successful assembled statewide model in project state so this repaired-geography handoff survives session restarts; users can still override the model path manually.

Custom Marea aggregation is prototype-only. The reviewed draft contract, read-only preflight, and safe-subset executor live in metadata/drafts/marea_aggregation_contracts_reviewed.csv and R/runtime/custom_marea_aggregation_*.R. They write validation outputs only under outputs/generated_models/custom_marea_validation/ and are not wired into the production region build flow.

CMA-6A adds conservative copy_if_invariant support for marea_congestion_charges, marea_operations_deployment, and marea_speed_smooth_ecodrive. These policy/rate files are generated only when all selected component Mareas agree by field and year. Mixed operations or speed/eco-drive values block with selected-value reports; no policy/rate averaging or arbitrary value selection is performed. Rail defaults, transit biofuel mix, non-invariant UzaNameLookup overrides, and region_base_year_dvmt remain deferred.

CMA-6B promotes the Bus road-class split with a documented MBRevMi + RBRevMi bus-service proxy. This is not true bus DVMT. Positive bus service selections use weighted averages normalized to sum to 1; zero bus service selections copy invariant Bus split values if possible and otherwise block. marea_speed_smooth_ecodrive is year-invariant in current VA data and passes year-scoped invariant checks.

CMA-7 promotes reportable v0 modeler assumptions for RampMeterDeployProp, bus composition defaults, and rail composition. RampMeterDeployProp uses FwyLaneMi as a freeway facility-exposure proxy, not true freeway DVMT. Positive bus service with all-NA bus composition uses the same documented default as standardization. Rail CR all-NA composition defaults to diesel/ICEV; SR/HR all-NA composition defaults to EV powertrain with a visible fuel compatibility fill required by VE input checks.

CMA-8 promotes transit biofuel mix aggregation. Biofuel blend proportions are weighted by fuel-specific exposure derived from transit service and generated/approved transit fuel shares: gasoline exposure for ethanol, diesel exposure for biodiesel, and CNG exposure for RNG. Positive exposure uses weighted averages only. Zero-exposure cases are inactive and generate neutral 0 with assumption_id=biofuel_zero_exposure_neutral_default_v0; source values are still reported and no unweighted average is used. Non-invariant UzaNameLookup, region_base_year_dvmt, and partial missing transit composition groups remain unresolved.

CMA-9 preserves region_base_year_dvmt.csv unchanged in custom Marea validation outputs. VisionEval treats it as a Region control/lookup input; HvyTrkDvmt = NA is preserved so VE can apply its own default calculation. RegionBuilder adds diagnostics comparing populated regional heavy-truck DVMT to generated Marea heavy-truck sums, but it does not derive replacement Region values in v0. Non-invariant UzaNameLookup and partial missing transit composition groups remain unresolved.

CMA-10 partitions mixed UzaNameLookup selections instead of blocking or forcing one lookup onto all selected Azones. A selected Azone region can produce multiple generated custom Mareas, one per UZA lookup group, with blank lookups reported as non_uza. Custom UZA mapping and single-UZA override remain future modeler-decision features.

CMRB-1/CMRB-2 add a backend-only custom-Marea-fed region build prototype. The preflight consumes custom Marea aggregation readiness, plans generated Marea groups and rewritten geo.csv mapping, and checks required support files. The prototype runner builds a safe generated region model under outputs/generated_models/custom_marea_region_build*/, injects generated Marea-level inputs, preserves region_base_year_dvmt.csv, and does not run VisionEval.

MDR-1 adds backend modeler decision and assumption reporting in metadata/modeler_decision_registry.csv and R/runtime/modeler_decision_report.R. CMVE-1 adds R/runtime/custom_marea_visioneval_preflight.R, which checks custom-Marea-fed generated models, runs the road-performance blocker, reads decision reports, and still does not run VisionEval. The Shiny Region Build tab can now read and display existing custom-Marea-fed build, modeler decision, and custom-Marea VisionEval preflight reports. It also has a separate backend-only Custom Marea-fed Region Build Prototype section that can run CMRB preflight, CMRB build, and CMVE preflight with generated-output guardrails. It does not add decision editing, scenario planning, or VisionEval run authorization.

Shiny Diagnostic Prototype

Launch the internal diagnostic/configuration shell with:

Rscript scripts/launch_shiny_gui.R

With an explicit shared package library:

Rscript scripts/launch_shiny_gui.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4"

Normal launch starts the Shiny server in the foreground and is expected to keep running until you stop it with Ctrl+C, close the terminal session, or stop the R process.

For bounded validation that does not start the server:

Rscript scripts/launch_shiny_gui.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --check-only

This prototype displays the unified runtime setup report and validates selected paths. It can run explicitly gated workflow steps where buttons are already implemented, and it can read existing custom-Marea-fed backend reports. It does not run VisionEval unless the separate explicit VisionEval run controls are used on the Run VisionEval tab; no custom-Marea VisionEval run controls are added. The custom-Marea prototype flow requires output workspaces under outputs/generated_models/, shows the planned generated model path, blocks existing outputs unless overwrite is checked, and rejects overly long output paths that would break nested Windows report files. The shiny and processx packages must already be installed in the R version used to launch it.

VisionEval Mode 1 is supported in the prototype: enter an existing VisionEval folder containing VisionEval.R, check it, then save the repo-local development runtime config at outputs/logs/local_runtime_dev.yml. Setup diagnostics use explicit arguments first, then that config, then environment variables, then defaults. Bundled VisionEval installation remains planned but unimplemented.

Project Paths persistence is also supported in the prototype. The Shiny Project Paths tab saves template model, Virginia statewide input, output workspace, optional runtime config, project name, and notes to:

outputs/logs/project_paths_dev.yml

The tab then refreshes a preflight report with path statuses only. Workflow execution remains disabled in the GUI.

VA Input Preflight is available as a Stage 6A diagnostic. It reads metadata/va_input_standardization_manifest.csv, checks the persisted va_input_path, and can write:

outputs/logs/va_input_preflight_dev.json

It reports missing, present, unreadable, and found-unverified files plus planned rule groups. It does not standardize inputs or assemble a model.

Input Contract Preflight is available as a read-only registry diagnostic. It compares raw or standardized input files to the reviewed VE-driven registry:

Rscript R/runtime/input_contract_preflight.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --mode=auto

Reports are written under outputs/logs/input_contract_preflight/. This step does not run standardization or rewrite inputs.

VA Input Standardization is available as a Stage 6B non-destructive execution step. It is manifest-driven: each expected file is resolved, read or copied safely, written as a generated copy, and reported. Narrow compatibility exceptions are registry-backed and reported. Outputs are written under:

<output_workspace>/standardized_inputs/current/

Run it from the command line with:

Rscript R/runtime/va_input_standardize.R --input-root="C:/path/to/updatedcsvs" --output-workspace="outputs/generated_models"

The Shiny tab exposes the same step behind an explicit button, with technical details collapsed by default. It does not run statewide assembly.

Current narrow repairs include dropping fully blank azone_per_cap_inc export rows only in generated standardized outputs and applying confirmed metadata-backed Azone spelling corrections to standardized outputs. Blank Geo/Year rows with values still block, and source VA inputs are preserved.

Marea transit service, fuel, powertrain, and biofuel mix files have explicit validation contracts. Fuel and powertrain all-NA groups with zero service are preserved, Van/Bus all-NA groups with positive service receive documented v0 modeler defaults, partial NA/populated groups block for modeler decision, and Rail defaults are not applied.

Stage 7A adds a preflight-only standardized assembly adapter. It checks that standardized_inputs/current/updated_csvs can feed the existing statewide CSV mapping logic and that support_files contains 42_model_parameters.json or another model_parameters.json variant, geo.csv, and deflators.csv.

Stage 7B adds gated statewide assembly from standardized inputs. It creates a generated statewide model copy, injects standardized CSVs plus support files, and writes reports under:

<output_workspace>/assembly/current/reports/

The Shiny Statewide Assembly tab enables Run Assembly only when preflight is ready. This step does not run VisionEval or build a region.

Stage 8A adds region-build preflight and gated region-build execution from a generated statewide model. It validates required statewide model files, manifest inputs, region config/Marea selection, and output workspace before building. The Shiny Region Build tab enables Run Region Build only when preflight is ready. This step creates a generated region model and does not run VisionEval.

Stage 8B requires explicit region selection in the product wrapper and Shiny flow. The user must provide a region config path; the product path does not silently default to Greater Richmond. The legacy scripts/build_region_model.R entry point keeps its existing script default separately.

Stage 8C adds GUI-assisted region config creation. The Region Build tab can load available Mareas from the selected generated statewide model's defs/geo.csv, write a valid config under outputs/generated_models/region_configs/, and use that saved config for preflight/build. Users no longer need to hand-write YAML for the GUI path. Existing region config paths must point to a .yml or .yaml file, not the configs/ folder. Surrounding quotes pasted around path inputs are tolerated.

Stage 8D adds prototype-only Azone-first region preflight. It lets users select Azones, derives Bzones from defs/geo.csv, reports affected/partial Mareas, and surfaces confirmed geography data-quality issues such as the Clarke/Charlotte Marea assignment. It can generate a legacy-compatible region config only when preflight is ready under legacy_compatible_only; the existing Region Build path then consumes that config.

G1 adds metadata-backed geography contract repair during standardization. Confirmed repairs from metadata/geo_relationship_known_issues.csv are applied only to generated standardized support_files/geo.csv; source inputs and existing generated models are not patched in place.

Confirmed Azone value spelling corrections live in metadata/geo_value_known_corrections.csv. They are exact replacements in generated standardized outputs, including explicit geo.csv Azone crosswalk rows, so standardized outputs use canonical Azone names.

FC-2C adds metadata/input_file_column_shape_overlays.csv so read-only preflight can recognize confirmed suffix/shape patterns without broadly relaxing contracts. FC-3 adds a report-only helper:

Rscript R/runtime/contract_driven_standardization_subset.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --preflight-dir="outputs/logs/input_contract_preflight/fc2c_shape_overlay_aware"

It reports the safe contract-driven validation/repair-wrapper subset and does not replace standardization.

Quick Smoke Test

Run the fixture smoke test to confirm that RegionBuilder works without external data:

The fixture is synthetic and is only intended to test RegionBuilder mechanics; it is not a Virginia statewide model.

Rscript scripts/run_fixture_smoke.R

Expected outputs:

outputs/generated_models/fixture_smoke/
outputs/reports/fixture_smoke_validation.csv

Prepare Virginia Statewide CSVs

Before assembling the statewide source model, normalize the Virginia statewide CSV input folder into the input contract expected by this project.

Rscript scripts/prepare_updatedcsvs_va_inputs.R "C:/path/to/updatedcsvs"

Pass your own updatedcsvs path explicitly. Do not rely on machine-specific defaults.

This step is safe to rerun. It validates and standardizes the Virginia statewide CSV input folder used by the statewide assembly step. When changes are needed, it writes backups outside that folder so backup files are not mistaken for model inputs.

The preparation step is intended for Virginia statewide CSV input folders. It preserves geography IDs as text, checks required year coverage, applies documented VisionEval compatibility adjustments, and verifies that required support files such as deflators.csv are available.

If you are using an already prepared Virginia statewide CSV input folder, this step should complete without changes and serves as a validation check.

Assemble Statewide Source Model

Standardized Inputs Path

For the Stage 6B/6C standardized workflow, run Stage 7B in dry-run mode first:

Rscript R/runtime/standardized_assembly_run.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --standardized-input-root="outputs/logs/stage6c_report_audit" --template-model-path="C:/path/to/template_model" --output-workspace="outputs/generated_models" --output-model-name="statewide_model" --dry-run

Actual generated-model assembly requires --run:

Rscript R/runtime/standardized_assembly_run.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --standardized-input-root="outputs/logs/stage6c_report_audit" --template-model-path="C:/path/to/template_model" --output-workspace="outputs/generated_models" --output-model-name="statewide_model" --run --overwrite

Stage 7B consumes:

standardized_inputs/current/
  updated_csvs/
  support_files/
  reports/

It copies the template model to <output_workspace>/assembly/current/<output-model-name>, replaces mapped CSVs, and injects support files:

support_files/*_model_parameters.json -> inputs/model_parameters.json
support_files/geo.csv                 -> defs/geo.csv
support_files/deflators.csv           -> defs/deflators.csv

Review these reports before building regions:

<output_workspace>/assembly/current/reports/assembly_run_summary.csv
<output_workspace>/assembly/current/reports/assembly_csv_mapping_report.csv
<output_workspace>/assembly/current/reports/assembly_support_injection_report.csv
<output_workspace>/assembly/current/reports/assembly_file_operations.csv
<output_workspace>/assembly/current/reports/assembly_findings.md

Stage 7B does not run VisionEval.

Legacy Config Path

Copy the example statewide assembly config:

Copy-Item configs/statewide_assembly.example.yml configs/statewide_assembly.yml

Edit configs/statewide_assembly.yml for your template model and prepared Virginia statewide CSV input folder:

paths:
  template_model_dir: C:/path/to/template_model
  updated_csv_dir: C:/path/to/updatedcsvs
  filelist_path: data_sources/filelist.txt
  manual_mapping_path: metadata/statewide_manual_file_mappings.csv
  column_renames_path: metadata/statewide_column_renames.csv
  geography_file: geo.csv
  geography_destination: defs/geo.csv
  output_model_dir: outputs/generated_models/statewide_va_clean
  report_path: outputs/reports/statewide_assembly_report.csv

explicit_file_injections:
  - source: deflators.csv
    destination: defs/deflators.csv
    notes: Inject updated deflators file into defs/deflators.csv.

required_deflator_years:
  - 2024

overwrite_output: true

Run statewide assembly:

Rscript scripts/assemble_statewide_model.R configs/statewide_assembly.yml

The assembly script copies the template model into:

outputs/generated_models/statewide_va_clean

Then it injects the prepared Virginia statewide CSV inputs into that generated copy according to data_sources/filelist.txt, metadata mappings, column rename rules, and explicit file injections.

Review the reports before building regions:

outputs/reports/statewide_assembly_report.csv
outputs/reports/statewide_column_rename_report.csv

Resolve missing, ambiguous, or unmapped required files before continuing.

Build a Regional Model

Gated Generated-Statewide Path

For the Stage 7B generated statewide workflow, run Stage 8A preflight first:

Rscript R/runtime/region_build_preflight.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --statewide-model-path="outputs/generated_models/assembly/current/stage7b_validation_statewide" --output-workspace="outputs/generated_models/stage8a_validation_workspace" --region-config-path="configs/greater_richmond.yml"

Then run the gated wrapper in dry-run mode:

Rscript R/runtime/region_build_run.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --statewide-model-path="outputs/generated_models/assembly/current/stage7b_validation_statewide" --output-workspace="outputs/generated_models/stage8a_validation_workspace" --region-config-path="configs/greater_richmond.yml" --dry-run

Actual region build requires --run and uses --overwrite to replace an existing generated region model:

Rscript R/runtime/region_build_run.R --lib="C:/Users/Jameson.Clements/Documents/R/win-library/4.4" --statewide-model-path="outputs/generated_models/assembly/current/stage7b_validation_statewide" --output-workspace="outputs/generated_models/stage8a_validation_workspace" --region-config-path="configs/greater_richmond.yml" --run --overwrite

Reports are written under:

<output_workspace>/region_build/current/reports/

This creates a generated region model. It does not run VisionEval.

In Shiny, users can either provide an existing region config path or create one from GUI fields: region name, output config path, and selected Mareas. Selected Mareas may be chosen from the loaded statewide geography list or entered as comma-separated / one-per-line text. If a folder such as configs/ is entered as an existing config, preflight shows a clear validation message and does not attempt YAML parsing.

Legacy Config Path

Copy the example region config:

Copy-Item configs/region.example.yml configs/my_region.yml

Edit configs/my_region.yml:

region:
  name: my_region
  model_region: My Region
  scenario: Base
  description: VERSPM for My Region model
  base_year: 2024
  years:
    - 2024
    - 2045
  mareas:
    - Example Marea
  region_geo_values:
    - Virginia
  czone_mode: auto

paths:
  source_model_dir: outputs/generated_models/statewide_va_clean
  output_model_dir: outputs/generated_models/my_region
  validation_report: outputs/reports/my_region_validation.csv

  # For real Virginia statewide builds, replace this with the manifest
  # supplied for your statewide input package.
  manifest: metadata/input_manifest.csv

  # Path to the VisionEval geography definition file inside the source model.
  geography_file: defs/geo.csv

The geography crosswalk is authoritative. Select the region by listing Mareas; RegionBuilder derives the allowed Azones and Bzones from the filtered geography file. czone_mode: auto writes VisionEval-compatible NA Czone values when the source geography has no meaningful Czone values.

Run the regional build:

Rscript scripts/build_region_model.R configs/my_region.yml

Expected outputs:

outputs/generated_models/my_region/
outputs/reports/my_region_validation.csv

The generated folder is a runnable VisionEval model structure. VisionEval creates results/ when the model is run.

Configure VisionEval Runtime

VisionEval is not included in this repository. The runtime is only required for checking and running generated models; preparation, assembly, and region building can be done before runtime configuration.

For a step-by-step Windows installation walkthrough, see INSTALL_VISIONEVAL_WINDOWS.md.

Configure the local runtime by copying the example config:

Copy-Item configs/local_runtime.example.yml configs/local_runtime.yml

configs/local_runtime.yml is ignored by git and may contain paths specific to your computer.

Set ve_home to the folder that contains VisionEval.R, not to the file itself:

ve_home: "C:/Path/To/Folder/Containing/VisionEval.R"
ve_runtime: "outputs/generated_models"

# Optional. PowerShell wrappers can use this path to launch the matching Rscript.
rscript: "C:/Path/To/R-4.4.2/bin/Rscript.exe"

Use forward slashes in YAML paths.

On Windows, the .cmd wrappers are the recommended run path. They avoid common PowerShell script execution-policy blocks and use VE_RSCRIPT when it is set.

Set VE_RSCRIPT to the R version required by your installed VisionEval runtime:

$env:VE_RSCRIPT = "$env:LOCALAPPDATA\Programs\R\R-4.4.2\bin\Rscript.exe"

Some R installations put Rscript.exe under bin\x64:

$env:VE_RSCRIPT = "$env:LOCALAPPDATA\Programs\R\R-4.4.2\bin\x64\Rscript.exe"

This sets VE_RSCRIPT for the current PowerShell session.

Check the runtime:

scripts\check_visioneval_runtime.cmd

A usable runtime should report that VE_HOME exists, VisionEval.R exists, and VisionEval startup succeeds.

PowerShell .ps1 wrappers are optional advanced alternatives. They may require per-command execution-policy handling:

powershell -ExecutionPolicy Bypass -File .\scripts\check_visioneval_runtime.ps1

The .cmd wrappers remain the primary recommended Windows path.

Run a Generated Region

After preparing inputs, assembling the statewide model, building the region, and configuring the runtime, use the Stage 9A gated runner to preflight or run the generated region model.

Dry-run/preflight is the default:

Rscript R\runtime\visioneval_run.R --region-model-path=outputs\generated_models\region_build\current\wppdc --config-path=outputs\logs\local_runtime_dev.yml

Actual execution requires --run:

Rscript R\runtime\visioneval_run.R --region-model-path=outputs\generated_models\region_build\current\wppdc --config-path=outputs\logs\local_runtime_dev.yml --run

The wrapper sets VisionEval environment variables only for the running R process, captures stdout/stderr to outputs/generated_models/visioneval_runs/current/logs/, and writes reports to outputs/generated_models/visioneval_runs/current/reports/. Preflight also runs the road-performance zero-denominator blocker and writes reports under outputs/generated_models/visioneval_runs/current/reports/road_performance_blocker/. If blocking zero-urban-population Marea conditions are found, the wrapper stops before loading VisionEval and requires a modeler decision. Preflight also writes road_performance_decision_options.csv and road_performance_decision_support.md beside the blocker reports. The Shiny Run VisionEval tab launches runs as background jobs, polls status/log files every second, and shows phase-based progress, current stage, elapsed time, log paths, report paths, and recent stdout/stderr previews. Actual execution remains explicit: use the Run VisionEval button in Shiny or --run on the CLI.

See docs/runtime/road_performance_blocker_v0.md for the WPPDC road-performance blocker and its input-based detection method. See docs/workflow/modeler_decision_layer_v0.md for the modeler decision note layer. G4B can save unresolved decision notes under outputs/generated_models/modeler_decisions/current/; these generated records document intended resolution only. The current v0 policy for road-performance findings is block-before-run with no run override.

The first file-contract registry foundation is documented in docs/input_contracts/input_file_contract_registry_v0.md. The canonical schema and generated registry are:

metadata/input_file_contract_schema.csv
metadata/input_file_contracts.csv

Coverage reports are written under outputs/logs/file_contract_registry/.

For the regenerated WPPDC case, the road-performance blocker is not caused by the transit composition defaults. It is the zero inferred urban dwelling-unit allocation / UrbanPop risk for Patrick County and Pittsylvania County in 2024 and 2045. Current decision options are to revise source inputs, revise the region or Marea strategy, document a future exclusion or custom Marea strategy, or defer.

The legacy wrapper remains available for existing command-line workflows:

scripts\run_region_model.cmd my_region

Replace my_region with the generated model folder name.

The wrapper sets the VisionEval runtime context and runs the VE-3 model object API internally:

model <- openModel("my_region")
model$run()

Results are written under:

outputs/generated_models/<region_name>/results/

Recommended Windows command sequence:

Run the PowerShell commands first, then run the .cmd commands from the same repository root.

Rscript scripts/prepare_updatedcsvs_va_inputs.R "C:/path/to/updatedcsvs"
Rscript scripts/assemble_statewide_model.R configs/statewide_assembly.yml
Rscript scripts/build_region_model.R configs/my_region.yml
$env:VE_RSCRIPT = "$env:LOCALAPPDATA\Programs\R\R-4.4.2\bin\Rscript.exe"

scripts\check_visioneval_runtime.cmd
scripts\run_region_model.cmd my_region

Manifest Rules

The regional build uses the configured manifest to determine how each file is handled. A manifest row has:

file,geo_level,action,notes

Allowed geo_level values:

Region, Marea, Azone, Bzone, Czone

Allowed action values:

Action	Meaning
filter_geo	Keep rows whose Geo value belongs to the allowed geography list for that file.
copy	Copy the file unchanged.
review	Skip the file and record it in the validation report.

The generated geography file is written from the filtered statewide geography file and should not be listed as a copied manifest row.

The regional build manifest must match the statewide input package. The included metadata/input_manifest.csv is a sample manifest used by the fixture workflow. For Virginia statewide model builds, use the full manifest supplied with that input package, or set paths.manifest in the region config to the appropriate manifest file.

Generated Files and Local Configs

Generated files are written under:

outputs/generated_models/
outputs/reports/
outputs/logs/

Local configs are excluded from git because they contain machine-specific paths. Copy the examples and edit the copies:

configs/statewide_assembly.example.yml -> configs/statewide_assembly.yml
configs/region.example.yml             -> configs/my_region.yml
configs/local_runtime.example.yml      -> configs/local_runtime.yml

Only example config files are intended to be shared in the repository.

Custom-Marea Decision Resolution And VisionEval Gate

The custom-Marea-fed prototype now includes a minimal modeler decision resolution scaffold and a separate gated VisionEval run control.

• Decision resolution reads reports/modeler_decision_summary.csv and reports/modeler_decision_detail.csv from a generated model.
• Current v0 defaults can be accepted when no blocking/unresolved decisions exist.
• Custom override editing is not implemented yet.
• Blocking decisions remain blocked.
• ready_with_warnings custom-Marea preflight requires explicit accepted-default resolution before a custom-Marea-fed VisionEval run can be authorized.
• The custom-Marea-fed VisionEval run gate is separate from the normal Run VisionEval tab and reuses the existing non-blocking VisionEval runner.
• Custom-Marea-fed VisionEval preflight, gate, run reports, and logs default to a short run folder under outputs/generated_models/visioneval_runs/custom_marea/current/<safe_run_id>/ to avoid deeply nested Windows report paths.
• Automated validation uses dry-run/simulated paths and does not run actual VisionEval.

GUI Workflow State Bridge

The Shiny prototype now includes a collapsed Workflow Dashboard / Current Project State section backed by:

R/runtime/project_workflow_state.R
outputs/logs/project_workflow_state_dev.csv

This stores the latest runtime config, VA input path, output workspace root, assembled statewide model, selected Azones, custom region name, latest custom-Marea-fed model, decision status, CMVE status, and latest VE run path. Manual path entry remains available as advanced behavior while the GUI moves toward a workflow/state-driven model.

For custom-Marea-fed builds, users choose an output workspace root and the backend adds current/<safe_model_name> once. Supplying a workspace that already ends in current no longer produces current/current; supplying a generated model folder produces a warning.

CMRB blockers now include blocker count, top messages, file-level blockers, report path, and suggested next action. CMA-8 biofuel aggregation uses fuel-specific weighted averages for positive exposure. When gasoline, diesel, or CNG transit exposure is zero, the corresponding biofuel field is inactive and the generated value is set to neutral 0 with assumption_id=biofuel_zero_exposure_neutral_default_v0; source conflicts are reported and no unweighted average is used.

Internal Dev Launch

For team testing from a repo checkout, configure local paths in configs/dev_package/local_dev_paths.yml using configs/dev_package/local_dev_paths.example.yml as the template, then run:

scripts\launch_region_builder_dev.cmd

Use scripts\launch_region_builder_dev.cmd --check-only for a launcher preflight. This is a lightweight dev launcher, not a full installer. See docs/setup/internal_dev_package_v0.md.