Feat/gui2 stage5

GUI2_PLAN.md

@@ -79,7 +79,7 @@ implementation.
 | 2 | Complete | Added the packaged QML shell and Dataset/YAML/Save workflows |
 | 3 | Complete | Reached parity, migrated both launchers, retired Widgets, and qualified `0.1.0a4` |
 | 4 | Complete | Added controlled sweep and preparation worker operations for the existing public contracts |
-| 5 | Approved next | Add structured sweep and preparation QML workflows |
+| 5 | In progress | Structured Sweep, Preparation, and typed audit inspection are enabled; lifecycle hardening and qualification remain |
 | 6 | Pending | Build exact emitted-value 3D scenes |
 | 7 | Pending | Add native interactive 3D to QML |
 | 8 | Pending | Qualify native 3D packaging, platforms, and a later release |
@@ -192,7 +192,7 @@ The separate WSLg launch-hardening follow-up remains desktop maintenance. Its
 native XCB/WSLg acceptance passed on 2026-08-09 with a real six-row generation,
 configured plot, verified inspection, clean workspace reopen, and a fixed
 workspace-scoped smoke lifecycle; exhaustive verification now collects 837
-tests. Stage 5 is now the approved next stage.
+tests. Stage 5 is now in progress on its dedicated feature branch.
 
 ## Stage 5: sweep and preparation QML workflows
 
@@ -211,6 +211,191 @@ audits, partition summaries, correlations, singular values, rank, conditioning,
 and baseline metrics. Missing optional dependencies disable only the affected
 feature and provide exact installation guidance.
 
+### Implementation checkpoint: Units 1–22B
+
+Stage 5 is in progress on `feat/gui2-stage5`. The implemented checkpoint keeps
+one globally active configuration document while extending its exact-byte,
+dirty-state, reformat, external-change, atomic-Save, exclusive-Save-As, and
+saved-snapshot contracts across Dataset, Model Sweep, and Preparation YAML.
+`ConfigurationController` owns only that shared document lifecycle and the
+three focused drafts; workflow planning, execution, Activity, results,
+inspection, and Preparation source context remain in their existing focused
+controllers. Generic worker loading dispatches directly from the required
+`document_type` discriminator rather than parser order.
+
+The structured Model Sweep workflow is enabled in the normal QML shell. It
+supports the complete current sweep schema, comparison-plot snapshots and
+temporary editing, typed plan and result projections, revision-bound planning,
+controlled execution, cancellation, protected finalization, persistent
+finalized-result identity, and exact Inspect handoff.
+
+Preparation is implemented through the Unit 19B visible-shell checkpoint:
+
+- inspection derives a private typed preparation profile from verified source
+  metadata and established preparation field-resolution logic;
+- `PreparationWorkflowController` owns an explicit immutable copy of the
+  selected inspection snapshot, so later browsing in Inspect cannot silently
+  change the effective preparation source;
+- the complete current role, categorical, output, quality, baseline, and
+  eight-scenario schema is represented by Python-owned drafts;
+- temporary scenario edits survive navigation and cannot leak into Save,
+  validation, planning, execution, document replacement, workspace
+  replacement, or shutdown;
+- preparation planning, execution, cancellation, protected finalization,
+  Activity, result relation, and exact Inspect handoff consume the global
+  saved document plus the explicit source binding; and
+- the packaged `PreparationPage` and scenario editor are available through
+  normal navigation, the Workspace source prerequisite, the global command
+  lifecycle, and the workflow context inspector.
+
+Unit 19A adds the Python-owned New Preparation lifecycle. The configuration
+controller composes the packaged Preparation template through the global
+document lifecycle, while the desktop composition requires an explicit bound
+source before creation. A missing binding produces an exact prerequisite and
+routes to Inspect; direct internal configuration calls cannot bypass that
+composition guard. No new QML surface is enabled by 19A.
+
+Unit 19B enables the normal Preparation surface without adding another state
+owner. Workspace creation routes an unbound user to Inspect, dirty replacement
+uses the global discard decision, Preparation documents open directly in the
+structured page, and navigation, command status, focus routing, context state,
+and source-change actions bind the existing authoritative controllers. Focused
+QML coverage also holds optional ML and analysis controls unavailable under an
+app-only capability projection while keeping the page usable.
+
+Unit 20A begins finalized audit exposure without adding presentation state.
+Current Preparation `quality_flags` are now an integrity-verified table in the
+worker inspection catalog and therefore contribute to the exact inspection
+revision and reuse the established 500-row worker blocks and 100-row local
+pages. An invalid optional flags artifact remains omitted from table control and
+is reported through the existing Preparation quality error instead of making
+the main bundle uninspectable.
+
+Unit 20B adds the Qt-independent `PreparationAuditProjection` and its exact
+role contracts. It validates and deterministically flattens finalized quality,
+scenario and partition, duplicate-state, structured-grid, matrix, correlation,
+singular-value, and baseline evidence into detached typed rows. Missing numeric
+evidence has explicit availability state, mismatched worker evidence is
+rejected, and absent scenario-detail evidence never produces inferred leakage
+claims. A versioned private scenario-detail input is defined for the verified
+`scenario.json` evidence that Unit 20C will supply; no controller or QML wiring
+is part of Unit 20B.
+
+Unit 20C completes the private worker/controller integration. Current scenario
+audit artifacts are resolved within the finalized bundle, checked against their
+recorded hashes, read as exact bytes, and required to match the manifest's
+scenario name, kind, and partition counts before their leakage evidence enters
+the private worker payload. Their file identities contribute to the inspection
+revision. Legacy bundles without recorded scenario audit artifacts remain
+inspectable but expose no leakage evidence. A focused `PreparationAuditModel`
+owns the exact section list models, while `InspectionController` validates the
+complete projection before accepting the response, rejects audit data attached
+to another source kind, and clears audit state when inspection becomes stale.
+
+Unit 21A adds the reusable packaged `PreparationAuditView` without yet changing
+normal Inspect navigation. The component consumes only the focused typed audit
+object, groups quality/scenario, matrix, and baseline evidence into explicit
+sections, uses bounded reusable list delegates for potentially large evidence,
+and distinguishes unavailable evidence from an available section with no
+findings. It retains scenario, partition, fit, target, model, and source-group
+context in visible summaries, stacks its cards at narrow widths, and is directly
+instantiated with populated and unavailable projections under the QML warning
+capture. This deliberately leaves placement in the Inspect workflow to the
+separate Unit 21B integration boundary.
+
+Unit 21B integrates that component as a fifth Inspect tab only while a
+Preparation bundle has been successfully accepted. Dataset and Model Sweep
+inspections retain their existing four tabs. Current bundles present the typed
+quality/scenario, matrix, and baseline evidence plus exact artifact-level audit
+issues; legacy bundles retain an explicit unavailable state rather than losing
+the audit surface or fabricating evidence. Starting another inspection, a
+failed or stale inspection, or accepting a non-Preparation source hides the tab
+and returns a selected audit tab to Summary. The page remains responsive at
+narrow widths, and QML continues to consume only the controller's typed models.
+
+The native inspection checkpoint after Unit 21B found and repaired two
+presentation-path defects before lifecycle hardening continued. Text-only
+`AppButton` instances marked compact now retain visible labels instead of
+rendering as empty squares; the Preparation source card exposes visible bind,
+clear, and continuation actions, while the empty Preparation page can create a
+bound-source document without a Workspace detour. Scenario Add, Edit, Commit,
+Cancel, list mutation, and nested-editor model changes now cross the existing
+queued root-signal boundary, preventing a Loader/model rebind inside its own
+native click handler. Continued native inspection exposed the same synchronous
+rebind defect when Matrix diagnostics revealed its settings. Source actions,
+roles, categorical settings, source policy, outputs, matrix diagnostics, and
+baseline diagnostics now all cross that queued boundary as well. Focused QML
+interaction coverage invokes the visible Scenario and Matrix controls rather
+than substituting direct Python calls. Native reinspection confirmed that the
+source, Scenario, Matrix, and Baseline controls no longer crash. It also found
+that populated quality fields lost their placeholder-only descriptions and the
+shorter Outputs card was vertically centered as Quality diagnostics expanded.
+The five settings now retain persistent visible labels and both cards remain
+top-aligned. Native visual reinspection confirmed that the labels remain
+visible and the Outputs and Quality diagnostics headings remain aligned while
+both diagnostic sections are toggled. The Unit 21B presentation checkpoint is
+therefore accepted.
+
+Unit 22A hardens terminal-response adoption without adding another request or
+identity framework. Configuration requests now retain the workspace,
+document-replacement generation, document kind, exact validation bytes, and
+requested source relevant to that operation. Inspection requests retain the
+workspace, source, revision, table, worker-block offset, and local-page offset.
+Workflow requests retain the workspace, requested configuration path, exact
+active saved snapshot, and immutable execution plan/source context. A matching
+request UUID remains necessary, but a terminal success or failure is adopted
+only while this operation-specific semantic context is still current. This
+prevents late validation, Save, load, inspection, preview, plan, or execution
+responses from replacing newer state after direct or otherwise forbidden
+context mutation. Worker load results must also return the exact requested
+source, and preview payloads must identify the requested worker block.
+
+These guards preserve intentional semantics: ordinary edits made during an
+execution do not change its captured snapshot, and navigation or identical
+semantic state does not invalidate a response. Focused controller tests cover
+obsolete successes and failures, identical-byte document replacement,
+no-write stale Save, source mismatches, preview-block mismatches, and workspace
+replacement. Cross-controller action enforcement and shutdown/transition
+hardening were deliberately left to separate Units 22B and 22C.
+
+Unit 22B completes the cross-controller action-enforcement half of that
+boundary. Every QML-callable global configuration lifecycle or worker-start
+slot rechecks both transient-editor state and global request idleness in
+`DesktopController`; disabled controls are presentation only. Direct Plan and
+Execute calls focus the active comparison or scenario editor instead of
+reaching a workflow controller. Dataset and configured-Visualization edit
+slots now use the same document-kind and operation-aware `canEdit` policy that
+already guarded Sweep and Preparation fields. Configuration validation, load,
+Save, and planning lock their owning editor, while Dataset, Sweep, or
+Preparation execution continues to allow ordinary draft edits beside its
+immutable active snapshot. Session-plot field and mapping slots likewise reject
+changes while their render worker owns the submitted request. Cancellation and
+Force Stop remain available only through their established active-operation
+controllers.
+
+Focused facade regressions call the Python slots directly, bypassing QML
+enablement. They cover every global lifecycle and worker-start family, both
+nested-editor kinds, Dataset and Visualization editing under configuration
+work and execution, owned-object checks, and session rendering. Unit 22C still
+owns multi-step shutdown and the remaining cross-workflow transition matrix.
+
+No public YAML schema, CLI command, Python API, scientific algorithm, manifest,
+result model, artifact layout, provenance contract, or dependency boundary has
+changed. Focused tests accompany each completed implementation unit; the
+complete Stage 5 gate and native acceptance remain pending.
+
+The remaining implementation order after Unit 22B is:
+
+1. Unit 22C completes multi-step shutdown and cross-workflow transition
+   hardening.
+2. Unit 23 qualifies packaged Stage 5 QML and runs the complete gate.
+3. Unit 24 records completion only after automated and manual acceptance.
+
+The Unit 21B audit-presentation checkpoint and its focused native repair cycle
+are complete. Lifecycle paths are inspected after Unit 22C, and the final
+installed application after Unit 23; acceptance must not be deferred until the
+documentation-only completion unit.
+
 ## Stage 6: exact scientific 3D scenes
 
 Worker-prepared scenes support dataset runs and prepared main or scenario

ML_PREPARATION_ROADMAP.md

@@ -50,6 +50,54 @@ auxiliary export is explicitly enabled. The manifest records the original
 column, vocabulary, code order, missing-value code, dtype, and output-array
 name.
 
+## Desktop exposure checkpoint
+
+GUI-2 Stage 4 established worker-authoritative, revision-bound Preparation
+planning and execution without adding a visible editor. Stage 5 is now
+implemented through Unit 21B:
+
+- Inspect derives typed Preparation eligibility and capability projections
+  from verified dataset-run or model-sweep metadata;
+- the Preparation workflow explicitly binds a copied inspection path,
+  revision, descriptor, and profile, so ordinary inspection of another
+  artifact cannot silently change scientific execution context;
+- source context remains outside portable Preparation YAML and source changes
+  never rewrite selected configuration;
+- Python-owned drafts expose the complete current features, categoricals,
+  targets, auxiliary fields, source policy, outputs, matrix settings, baseline
+  settings, all eight scenario kinds, and ordered transformations;
+- planning and execution consume an exact saved Preparation snapshot plus the
+  explicit binding, and finalized results retain current, stale, or unrelated
+  identity independently of page lifetime; and
+- the packaged Preparation page and scenario editor are enabled through normal
+  navigation, guarded Workspace creation, global document commands, source
+  actions, and typed workflow context state; and
+- finalized `data/quality_flags.parquet` is available through the same
+  containment-checked, hash-verified, revision-bound, and bounded table-preview
+  path as other Preparation tables, while corruption remains a reported quality
+  issue rather than hiding the main bundle; and
+- a Qt-independent audit projection validates and deterministically flattens
+  finalized scenario, partition, duplicate-state, structured-grid, matrix,
+  correlation, singular-value, and baseline evidence into typed row contracts,
+  with explicit missing-value state and no inferred leakage claims when verified
+  scenario-detail evidence is absent; and
+- the worker supplies those scenario details only after bundle containment,
+  recorded-hash, exact-byte, name, kind, and partition checks, while their file
+  identities contribute to the inspection revision; the inspection controller
+  validates the full projection before publishing its focused typed models and
+  clears them when inspection becomes stale; and
+- a reusable packaged audit component presents those exact models in bounded,
+  contextual, responsive quality/scenario, matrix, and baseline sections and is
+  directly tested with populated and unavailable evidence; and
+- Inspect exposes that component only for a successfully accepted Preparation
+  bundle, keeps exact audit-artifact issues beside accepted evidence, preserves
+  explicit legacy-unavailable state, and hides an obsolete selected audit tab
+  when the inspected source changes.
+
+This is desktop exposure of the implemented preparation contract, not new
+preparation science. Lifecycle hardening, packaged qualification, and native
+acceptance remain later Stage 5 work.
+
 ## Reviewed future direction — Optional PyTorch dataset export
 
 The product sequence now prioritizes desktop workflow depth and then source