KSLCore/ksl.app.results.batchreports/BatchReportsWriter

BatchReportsWriter

Reporting layer shared by every host that materialises per-batch reports (Scenario today; Experiment when its tabs land).

Batches are represented as RunResult.BatchCompleted, and each snapshot in BatchCompleted.snapshots is an "item" — the domain-neutral name covering Scenario-app scenarios, Experiment-app design points, and anything else a future orchestrator emits. All item-name lookups go through the substrate's authoritative identifier — ExperimentCompleted.experiment.exp_name — which the bridge populates from model.experimentName, which the orchestrator sets from each item's name.

Every render path writes one file per selected ReportFormat and returns a WriteOutcome describing the paths written and any per-format errors. The writer does not open files in a browser or any other viewer — that's a host concern. Callers that want browser-open behavior consult WriteOutcome.htmlPath and dispatch through their own platform-appropriate channel (e.g. java.awt.Desktop.browse in a Swing host, a target="_blank" in a web host).

File-stem defaults

The default file stems (scenario-summary-* and scenario-summaries) preserve the names the Scenario app has been writing to disk, so existing user files are still recognised by perItemReportFiles / mostRecentItemFile after the rename. New hosts (e.g. Experiment app) override itemFileStemPrefix / batchFileStem for domain-natural names.

Types

FileHandlingPolicy

enum FileHandlingPolicy : Enum<BatchReportsWriter.FileHandlingPolicy>

Policy applied at write time when a destination file already exists for the target stem. Picked by the user via the reports tab's File-handling group; passed through to both renderItemSummary and renderBatchSummary on every Generate.

WriteOutcome

data class WriteOutcome(val written: List<Path>, val errors: List<String>, val skipped: Boolean = false)

Result of a render call. Lets the caller surface per-format successes and errors in one notification pass, and locate the HTML output (if any) for host-side browser-open.

Functions

availableItemNames

fun availableItemNames(result: RunResult.BatchCompleted): List<String>

Item names available for report generation — those that produced a completed snapshot, in the order the orchestrator committed them. Drives GUI pickers.

mostRecentItemFile

fun mostRecentItemFile(reportsDir: Path, itemName: String, itemFileStemPrefix: String = "scenario-summary"): Path?

Most-recently-modified file from perItemReportFiles, or null when none exist. This is what the tab opens when the user clicks a row's Open button.

mostRecentSummaryFile

fun mostRecentSummaryFile(reportsDir: Path, batchFileStem: String = "scenario-summaries"): Path?

As mostRecentItemFile but for the consolidated batch summary.

perItemReportFiles

fun perItemReportFiles(reportsDir: Path, itemName: String, itemFileStemPrefix: String = "scenario-summary"): List<Path>

All files in reportsDir that look like a per-item report for itemName — both the base-stem form and any timestamped variants written under FileHandlingPolicy.APPEND_TIMESTAMP. Used by the tab's Status / Open / Delete affordances.

renderBatchSummary

fun renderBatchSummary(result: RunResult.BatchCompleted, outputDir: Path, formats: Set<ReportFormat>, itemNames: Set<String>? = null, existingFilePolicy: BatchReportsWriter.FileHandlingPolicy = FileHandlingPolicy.OVERWRITE, batchFileStem: String = "scenario-summaries", reportTitle: String = "Batch Summary — ", itemTypeNamePlural: String = "scenarios", itemColumnHeader: String = "Scenario"): BatchReportsWriter.WriteOutcome

Primary on-demand report. One document covering every completed item (or a caller-supplied subset). Sections:

renderItemSummary

fun renderItemSummary(result: RunResult.BatchCompleted, itemName: String, outputDir: Path, formats: Set<ReportFormat>, existingFilePolicy: BatchReportsWriter.FileHandlingPolicy = FileHandlingPolicy.OVERWRITE, itemFileStemPrefix: String = "scenario-summary", reportTitle: String = "Item Summary — "): BatchReportsWriter.WriteOutcome

Render a single-item summary report for itemName using the substrate's existing snapshotSimulationResults pipeline. Includes everything the snapshot supports: run summary, across-replication statistics, histograms, frequencies, time-series period statistics.

summaryReportFiles

fun summaryReportFiles(reportsDir: Path, batchFileStem: String = "scenario-summaries"): List<Path>

As perItemReportFiles but for the consolidated batch summary.