KSLCore/ksl.app.session/AppWorkspacePaths

AppWorkspacePaths

Filesystem-path conventions for multi-document UI applications (Scenario, Experiment, Simopt today; any future non-Swing host tomorrow) that group all their per-app artefacts under a single subdirectory of the user's active workspace.

Lays out a stable directory shape:

<activeWorkspace>/                       ← user-wide root from UserSettingsStore
    <sanitizeAppName(appName)>/            ← appWorkspaceDir
      output/
        <sanitizeAnalysisName(name)>/      ← outputDir
          reports/                         ← reportsDir

Pure functions over Path / String — no Swing dependency, no live engine state. Any host application that wants to honour this standard layout (so users can navigate between analyses in a file manager with stable expectations) calls these.

Relationship to other path objects

ksl.app.settings.WorkspaceLayout covers the scenario workflow §2 runId-keyed layout (<workspace>/output/<runId>/). Different convention, different consumers.
ksl.app.optimization.paths.OptimizationPaths adds optimization-specific helpers (run-NNN subdirectories, trace files) on top of this layout. Its outputDir(...) delegates here.

Single-document hosts (single-app today) deliberately use a different convention — nesting by analysisName at the workspace level rather than by appName — and do not call these helpers.

Substrate-level API — usable by any UI shell.

Functions

appWorkspaceDir

fun appWorkspaceDir(activeWorkspace: Path, appName: String): Path

Resolves <activeWorkspace>/<sanitizeAppName(appName)>/. The directory is not created by this helper.

outputDir

fun outputDir(appWorkspace: Path, analysisName: String): Path

Resolves <appWorkspace>/output/<sanitizeAnalysisName(analysisName)>/. Caller supplies the host's appWorkspace (typically computed via appWorkspaceDir). The directory is not created by this helper.

reportsDir

fun reportsDir(appWorkspace: Path, analysisName: String): Path

Resolves <outputDir(appWorkspace, analysisName)>/reports/. Convenience composition for hosts that materialise their rendered reports under the standard reports/ subdirectory of the analysis output. The directory is not created by this helper.

sanitizeAppName

fun sanitizeAppName(appName: String): String

Filesystem-segment-safe form of appName — spaces become underscores. Idempotent on already-safe input. Used to derive the per-app subdirectory under the active workspace.