# Semantic Module Contracts: LLM Dataset Orchestration

**Feature**: [LLM Dataset Orchestration](../spec.md)  
**Branch**: `027-dataset-llm-orchestration`

This document defines the semantic contracts for the core components of the Dataset LLM Orchestration feature, following the [GRACE-Poly Standard](../../../.ai/standards/semantics.md).

---

## 1. Backend Modules

# [DEF:DatasetReviewOrchestrator:Module]
# @COMPLEXITY: 5
# @PURPOSE: Coordinate the full dataset review session lifecycle across intake, recovery, semantic review, clarification, mapping review, preview generation, and launch.
# @LAYER: Domain
# @RELATION: [DEPENDS_ON] ->[DatasetReviewSessionRepository]
# @RELATION: [DEPENDS_ON] ->[SemanticSourceResolver]
# @RELATION: [DEPENDS_ON] ->[ClarificationEngine]
# @RELATION: [DEPENDS_ON] ->[SupersetContextExtractor]
# @RELATION: [DEPENDS_ON] ->[SupersetCompilationAdapter]
# @RELATION: [DEPENDS_ON] ->[TaskManager]
# @PRE: session mutations must execute inside a persisted session boundary scoped to one authenticated user.
# @POST: state transitions are persisted atomically and emit observable progress for long-running steps.
# @SIDE_EFFECT: creates task records, updates session aggregates, triggers upstream Superset calls, persists audit artifacts.
# @DATA_CONTRACT: Input[SessionCommand] -> Output[DatasetReviewSession | CompiledPreview | DatasetRunContext]
# @INVARIANT: Launch is blocked unless a current session has no open blocking findings, all launch-sensitive mappings are approved, and a non-stale Superset-generated compiled preview matches the current input fingerprint.
# @TEST_CONTRACT: start_or_resume_session -> returns persisted session shell with recommended next action
# @TEST_SCENARIO: launch_gate_blocks_stale_preview -> launch rejected when preview fingerprint no longer matches current mapping inputs
# @TEST_EDGE: missing_dataset_ref -> blocking failure
# @TEST_EDGE: stale_preview -> blocking failure
# @TEST_EDGE: sql_lab_launch_failure -> terminal failed launch state with audit record
# @TEST_INVARIANT: launch_gate -> VERIFIED_BY: [launch_gate_blocks_stale_preview]

#### ƒ **start_session**
# @PURPOSE: Initialize a new session from a Superset link or dataset selection and trigger context recovery.
# @PRE: source input is non-empty and environment is accessible.
# @POST: session exists in persisted storage with intake/recovery state and task linkage when async work is required.
# @SIDE_EFFECT: persists session and may enqueue recovery task.

#### ƒ **apply_semantic_source**
# @PURPOSE: Apply a selected semantic source and update field-level candidate/decision state.
# @PRE: source exists and session is not terminal.
# @POST: semantic field entries and findings reflect selected-source outcomes without overwriting locked manual values.
# @SIDE_EFFECT: updates semantic decisions and conflict findings.

#### ƒ **record_clarification_answer**
# @PURPOSE: Persist one clarification answer and re-evaluate profile, findings, and readiness.
# @PRE: target question belongs to the session’s active clarification session.
# @POST: answer is saved before current-question pointer advances.
# @SIDE_EFFECT: updates clarification and finding state.

#### ƒ **prepare_launch_preview**
# @PURPOSE: Assemble effective execution inputs and trigger Superset-side preview compilation.
# @PRE: all required variables have candidate values or explicitly accepted defaults.
# @POST: returns preview artifact in pending, ready, failed, or stale state.
# @SIDE_EFFECT: persists preview attempt and upstream compilation diagnostics.

#### ƒ **launch_dataset**
# @PURPOSE: Start the approved dataset execution through SQL Lab and persist run context for audit/replay.
# @PRE: session is run-ready and compiled preview is current.
# @POST: returns persisted run context with SQL Lab session reference and launch outcome.
# @SIDE_EFFECT: creates SQL Lab execution session and audit snapshot.

# [/DEF:DatasetReviewOrchestrator:Module]

---

# [DEF:DatasetReviewSessionRepository:Module]
# @COMPLEXITY: 5
# @PURPOSE: Persist and retrieve dataset review session aggregates, including readiness, findings, semantic decisions, clarification state, previews, and run contexts.
# @LAYER: Domain
# @RELATION: [DEPENDS_ON] ->[DatasetReviewSession]
# @RELATION: [DEPENDS_ON] ->[DatasetProfile]
# @RELATION: [DEPENDS_ON] ->[ValidationFinding]
# @RELATION: [DEPENDS_ON] ->[CompiledPreview]
# @PRE: repository operations execute within authenticated request or task scope.
# @POST: session aggregate reads are structurally consistent and writes preserve ownership and version semantics.
# @SIDE_EFFECT: reads/writes application persistence layer.
# @DATA_CONTRACT: Input[SessionMutation] -> Output[PersistedSessionAggregate]
# @INVARIANT: answers, mapping approvals, preview artifacts, and launch snapshots are never attributed to the wrong user or session.
# @TEST_CONTRACT: save_then_resume -> persisted session can be reopened without losing semantic/manual/clarification state
# @TEST_SCENARIO: resume_session_preserves_manual_overrides -> locked semantic fields remain active after reload
# @TEST_EDGE: foreign_user_access -> rejected
# @TEST_EDGE: missing_session -> not found
# @TEST_EDGE: partial_preview_snapshot -> preserved but not marked launchable
# @TEST_INVARIANT: ownership_scope -> VERIFIED_BY: [foreign_user_access]

#### ƒ **create_session**
# @PURPOSE: Persist initial session shell.

#### ƒ **load_session_detail**
# @PURPOSE: Return the full session aggregate for API/frontend use.

#### ƒ **save_profile_and_findings**
# @PURPOSE: Persist profile and validation state together.

#### ƒ **save_preview**
# @PURPOSE: Persist compiled preview attempt and mark older fingerprints stale.

#### ƒ **save_run_context**
# @PURPOSE: Persist immutable launch audit snapshot.

# [/DEF:DatasetReviewSessionRepository:Module]

---

# [DEF:SemanticSourceResolver:Module]
# @COMPLEXITY: 4
# @PURPOSE: Resolve, rank, and apply semantic metadata candidates from files, connected dictionaries, reference datasets, and AI generation fallback.
# @LAYER: Domain
# @RELATION: [DEPENDS_ON] ->[LLMProviderService]
# @RELATION: [DEPENDS_ON] ->[SemanticSource]
# @RELATION: [DEPENDS_ON] ->[SemanticFieldEntry]
# @RELATION: [DEPENDS_ON] ->[SemanticCandidate]
# @PRE: selected source and target field set must be known.
# @POST: candidate ranking follows the configured confidence hierarchy and unresolved fuzzy matches remain reviewable.
# @SIDE_EFFECT: may create conflict findings and semantic candidate records.
# @DATA_CONTRACT: Input[SemanticSourceSelection | SemanticFieldSet | ManualFieldDecision] -> Output[SemanticCandidateSet | RankedSemanticResolution | ValidationFindingSet]
# @INVARIANT: Manual overrides are never silently replaced by imported, inferred, or AI-generated values.
# @TEST_CONTRACT: rank_candidates -> exact dictionary beats reference import beats fuzzy beats AI draft
# @TEST_SCENARIO: manual_lock_survives_reimport -> locked field remains active after another source is applied
# @TEST_EDGE: malformed_source_payload -> failed source application with explanatory finding
# @TEST_EDGE: conflicting_sources -> conflict state preserved for review
# @TEST_EDGE: no_trusted_matches -> AI draft fallback only
# @TEST_INVARIANT: confidence_hierarchy -> VERIFIED_BY: [rank_candidates]

#### ƒ **resolve_from_file**
# @PURPOSE: Normalize uploaded semantic file records into field-level candidates.

#### ƒ **resolve_from_dictionary**
# @PURPOSE: Resolve candidates from connected tabular dictionary sources.

#### ƒ **resolve_from_reference_dataset**
# @PURPOSE: Reuse semantic metadata from trusted Superset datasets.

#### ƒ **rank_candidates**
# @PURPOSE: Apply confidence ordering and determine best candidate per field.

#### ƒ **detect_conflicts**
# @PURPOSE: Mark competing candidate sets that require explicit user review.

#### ƒ **apply_field_decision**
# @PURPOSE: Accept, reject, or manually override a field-level semantic value.

# [/DEF:SemanticSourceResolver:Module]

---

# [DEF:ClarificationEngine:Module]
# @COMPLEXITY: 4
# @PURPOSE: Manage one-question-at-a-time clarification sessions, including prioritization, answer persistence, and readiness impact updates.
# @LAYER: Domain
# @RELATION: [DEPENDS_ON] ->[ClarificationSession]
# @RELATION: [DEPENDS_ON] ->[ClarificationQuestion]
# @RELATION: [DEPENDS_ON] ->[ClarificationAnswer]
# @RELATION: [DEPENDS_ON] ->[ValidationFinding]
# @PRE: target session contains unresolved or contradictory review state.
# @POST: every recorded answer updates the clarification session and associated session state deterministically.
# @SIDE_EFFECT: creates clarification questions, persists answers, updates findings/profile state.
# @DATA_CONTRACT: Input[ClarificationSessionState | ClarificationAnswerCommand] -> Output[ClarificationQuestionPayload | ClarificationProgressSnapshot | SessionReadinessDelta]
# @INVARIANT: Clarification answers are persisted before the current question pointer or readiness state is advanced.
# @TEST_CONTRACT: next_question_selection -> returns only one highest-priority unresolved question at a time
# @TEST_SCENARIO: save_and_resume_clarification -> reopening session restores current question and prior answers
# @TEST_EDGE: skipped_question -> unresolved topic remains visible
# @TEST_EDGE: expert_review_marked -> topic deferred without false resolution
# @TEST_EDGE: duplicate_answer_submission -> idempotent or rejected deterministically
# @TEST_INVARIANT: single_active_question -> VERIFIED_BY: [next_question_selection]

#### ƒ **start_or_resume**
# @PURPOSE: Open clarification mode on the highest-priority unresolved question.

#### ƒ **build_question_payload**
# @PURPOSE: Return question, why-it-matters text, current guess, and suggested options.

#### ƒ **record_answer**
# @PURPOSE: Persist one answer and compute state impact.

#### ƒ **summarize_progress**
# @PURPOSE: Produce the clarification change summary shown on exit or pause.

# [/DEF:ClarificationEngine:Module]

---

# [DEF:SupersetContextExtractor:Module]
# @COMPLEXITY: 4
# @PURPOSE: Recover dataset, dashboard, filter, and runtime-template context from Superset links and related API payloads.
# @LAYER: Infra
# @RELATION: [DEPENDS_ON] ->[ImportedFilter]
# @RELATION: [DEPENDS_ON] ->[TemplateVariable]
# @RELATION: [DEPENDS_ON] ->[SupersetClient]
# @DATA_CONTRACT: Input[SupersetLink | DatasetReference | EnvironmentContext] -> Output[RecoveredSupersetContext | ImportedFilterSet | TemplateVariableSet | RecoverySummary]
# @PRE: Superset link or dataset reference must be parseable enough to resolve an environment-scoped target resource.
# @POST: returns the best available recovered context with explicit provenance and partial-recovery markers when necessary.
# @SIDE_EFFECT: performs upstream Superset API reads.
# @INVARIANT: Partial recovery is surfaced explicitly and never misrepresented as fully confirmed context.
# @TEST_CONTRACT: recover_context_from_link -> output distinguishes URL-derived, native-filter-derived, and unresolved context
# @TEST_SCENARIO: partial_filter_recovery_marks_recovery_required -> session remains usable but not falsely complete
# @TEST_EDGE: unsupported_link_shape -> intake failure with actionable finding
# @TEST_EDGE: dataset_without_filters -> successful dataset recovery with empty imported filter set
# @TEST_EDGE: missing_dashboard_binding -> partial recovery only
# @TEST_INVARIANT: provenance_visibility -> VERIFIED_BY: [recover_context_from_link]

#### ƒ **parse_superset_link**
# @PURPOSE: Extract candidate identifiers and query state from supported Superset URLs.

#### ƒ **recover_imported_filters**
# @PURPOSE: Build imported filter entries from URL state and Superset-side saved context.

#### ƒ **discover_template_variables**
# @PURPOSE: Detect runtime variables and Jinja references from dataset query-bearing fields.

#### ƒ **build_recovery_summary**
# @PURPOSE: Summarize recovered, partial, and unresolved context for session state and UX.

# [/DEF:SupersetContextExtractor:Module]

---

# [DEF:SupersetCompilationAdapter:Module]
# @COMPLEXITY: 4
# @PURPOSE: Interact with Superset preview compilation and SQL Lab execution endpoints using the current approved execution context.
# @LAYER: Infra
# @RELATION: [DEPENDS_ON] ->[CompiledPreview]
# @RELATION: [DEPENDS_ON] ->[DatasetRunContext]
# @RELATION: [DEPENDS_ON] ->[SupersetClient]
# @DATA_CONTRACT: Input[ApprovedExecutionContext | PreviewFingerprint | LaunchRequest] -> Output[CompiledPreview | PreviewFailureArtifact | DatasetRunContext | LaunchFailureAudit]
# @PRE: effective template params and dataset execution reference are available.
# @POST: preview and launch calls return Superset-originated artifacts or explicit errors.
# @SIDE_EFFECT: performs upstream Superset preview and SQL Lab calls.
# @INVARIANT: The adapter never fabricates compiled SQL locally; preview truth is delegated to Superset only.
# @TEST_CONTRACT: compile_then_launch -> launch uses the same effective input fingerprint verified in preview
# @TEST_SCENARIO: preview_failure_blocks_launch -> no SQL Lab session is created after failed preview
# @TEST_EDGE: compilation_endpoint_error -> failed preview artifact with readable diagnostics
# @TEST_EDGE: sql_lab_creation_error -> failed launch audit state
# @TEST_EDGE: fingerprint_mismatch -> launch rejected
# @TEST_INVARIANT: superset_truth_source -> VERIFIED_BY: [preview_failure_blocks_launch]

#### ƒ **compile_preview**
# @PURPOSE: Request Superset-side compiled SQL preview for the current effective inputs.

#### ƒ **mark_preview_stale**
# @PURPOSE: Invalidate previous preview after mapping or value changes.

#### ƒ **create_sql_lab_session**
# @PURPOSE: Create the canonical audited execution session after all launch gates pass.

# [/DEF:SupersetCompilationAdapter:Module]

---

## 2. Frontend Components

<!-- [DEF:DatasetReviewWorkspace:Component] -->
<!-- @COMPLEXITY: 5 -->
<!-- @PURPOSE: Main dataset review workspace coordinating session state, progressive recovery, semantic review, clarification, preview, and launch UX. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @RELATION: [BINDS_TO] ->[assistantChat] -->
<!-- @RELATION: [BINDS_TO] ->[taskDrawer] -->
<!-- @UX_STATE: Empty -> Show source intake with Superset link and dataset-selection entry actions. -->
<!-- @UX_STATE: Importing -> Show progressive recovery milestones as context is assembled. -->
<!-- @UX_STATE: Review -> Show summary, findings, semantic layer, filters, mapping, and next action. -->
<!-- @UX_STATE: Clarification -> Focus the user on one current clarification question while preserving wider session context. -->
<!-- @UX_STATE: Ready -> Show launch summary and unambiguous run-ready signal without hiding warnings. -->
<!-- @UX_FEEDBACK: Main CTA changes by readiness state and reflects current highest-value next action. -->
<!-- @UX_RECOVERY: Users can save, resume, or reopen an unfinished session without losing context. -->
<!-- @UX_REACTIVITY: Uses Svelte runes for session, readiness, preview, and task state derivation. -->
<!-- @INVARIANT: Navigation away from dirty session state must require explicit confirmation. -->
<!-- @TEST_CONTRACT: workspace_state_machine -> one and only one major readiness-driven CTA is primary at a time -->
<!-- @TEST_SCENARIO: resume_preserves_state -> reopening unfinished session restores current panel state and next action -->
<!-- @TEST_EDGE: session_load_failure -> error/recovery UI shown -->
<!-- @TEST_EDGE: stale_preview_after_mapping_change -> preview state flips to stale -->
<!-- @TEST_EDGE: unsaved_navigation -> guarded exit -->
<!-- @TEST_INVARIANT: primary_cta_alignment -> VERIFIED_BY: [workspace_state_machine] -->

#### ƒ **handleSourceSubmit**
<!-- @PURPOSE: Start a session from a Superset link or dataset selection. -->
<!-- @UX_FEEDBACK: Immediate optimistic intake acknowledgement plus recovery progress. -->

#### ƒ **handleResumeSession**
<!-- @PURPOSE: Reopen an existing paused or unfinished session. -->
<!-- @UX_FEEDBACK: Restores the session into the correct readiness-driven panel state. -->

#### ƒ **handleLaunch**
<!-- @PURPOSE: Execute the final launch action once run-ready gates pass. -->
<!-- @UX_STATE: Launching -> Disable CTA and expose progress/result handoff. -->
<!-- @UX_FEEDBACK: Success state links to SQL Lab and audit summary; failure preserves context and recovery path. -->

<!-- [/DEF:DatasetReviewWorkspace:Component] -->

---

<!-- [DEF:SourceIntakePanel:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: Collect initial dataset source input through Superset link paste or dataset selection entry paths. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @UX_STATE: Idle -> Empty intake form with two clear entry paths. -->
<!-- @UX_STATE: Validating -> Lightweight inline validation feedback. -->
<!-- @UX_STATE: Rejected -> Input error shown with corrective hint. -->
<!-- @UX_FEEDBACK: Recognized links are acknowledged before deeper recovery finishes. -->
<!-- @UX_RECOVERY: Users can correct invalid input in place without resetting the page. -->

#### ƒ **submitSupersetLink**
<!-- @PURPOSE: Validate and submit Superset link input. -->

#### ƒ **submitDatasetSelection**
<!-- @PURPOSE: Submit selected dataset/environment context. -->

<!-- [/DEF:SourceIntakePanel:Component] -->

---

<!-- [DEF:ValidationFindingsPanel:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: Present validation findings grouped by severity with explicit resolution and actionability signals. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[DatasetReviewWorkspace] -->
<!-- @UX_STATE: Blocking -> Blocking findings are visually dominant and block launch flow. -->
<!-- @UX_STATE: Warning -> Warnings remain visible with explicit approval or defer actions. -->
<!-- @UX_STATE: Informational -> Low-priority findings are collapsed or secondary. -->
<!-- @UX_FEEDBACK: Resolving or approving an item updates readiness state immediately. -->
<!-- @UX_RECOVERY: Users can jump from a finding directly to the relevant remediation area. -->

#### ƒ **groupFindingsBySeverity**
<!-- @PURPOSE: Project findings into blocking, warning, and informational groups. -->

#### ƒ **jumpToFindingTarget**
<!-- @PURPOSE: Focus the relevant review section for a selected finding. -->

<!-- [/DEF:ValidationFindingsPanel:Component] -->

---

<!-- [DEF:SemanticLayerReview:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: Review and edit semantic metadata for columns and metrics with provenance and conflict visibility. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @UX_STATE: Normal -> Show current semantic values and provenance badges. -->
<!-- @UX_STATE: Conflicted -> Show side-by-side competing semantic candidates for the same field. -->
<!-- @UX_STATE: Manual -> Show locked manual override and block silent overwrite. -->
<!-- @UX_FEEDBACK: Applying a semantic source or manual override updates provenance and readiness immediately. -->
<!-- @UX_RECOVERY: Users can keep current values, accept recommendations, or review candidates one by one. -->

#### ƒ **applyManualOverride**
<!-- @PURPOSE: Lock a field to a user-provided semantic value. -->
<!-- @UX_FEEDBACK: Field marked as manual override and source-import replacement is disabled. -->

#### ƒ **applyCandidateSelection**
<!-- @PURPOSE: Accept one candidate from conflicting or fuzzy semantic options. -->
<!-- @UX_FEEDBACK: Candidate badge state changes and conflict warning clears when appropriate. -->

<!-- [/DEF:SemanticLayerReview:Component] -->

---

<!-- [DEF:ClarificationDialog:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: One-question-at-a-time clarification surface for unresolved or contradictory dataset meanings. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @RELATION: [BINDS_TO] ->[assistantChat] -->
<!-- @UX_STATE: Question -> Show current question, why-it-matters text, current guess, and selectable answers. -->
<!-- @UX_STATE: Saving -> Disable controls while persisting answer. -->
<!-- @UX_STATE: Completed -> Show clarification summary and impact on readiness. -->
<!-- @UX_FEEDBACK: Each answer updates profile and findings without forcing a full page reload. -->
<!-- @UX_RECOVERY: Users can skip, defer to expert review, pause, and resume later. -->

#### ƒ **submitAnswer**
<!-- @PURPOSE: Save selected or custom clarification answer. -->

#### ƒ **skipQuestion**
<!-- @PURPOSE: Defer the current question while keeping it unresolved. -->

#### ƒ **pauseClarification**
<!-- @PURPOSE: Exit clarification mode without losing prior answers. -->

<!-- [/DEF:ClarificationDialog:Component] -->

---

<!-- [DEF:ExecutionMappingReview:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: Review mappings between imported filters and detected template variables, including transformed values and warning approvals. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @UX_STATE: Incomplete -> Required mapping values still missing. -->
<!-- @UX_STATE: WarningApproval -> Mapping rows require explicit approval before launch. -->
<!-- @UX_STATE: Approved -> All launch-sensitive mappings approved or overridden. -->
<!-- @UX_FEEDBACK: Mapping approvals or manual edits immediately re-evaluate preview staleness and readiness. -->
<!-- @UX_RECOVERY: Users can manually override transformed values instead of approving them as-is. -->

#### ƒ **approveMapping**
<!-- @PURPOSE: Explicitly approve a warning-level value transformation. -->
<!-- @UX_FEEDBACK: Warning cleared and launch checklist refreshed. -->

#### ƒ **overrideMappingValue**
<!-- @PURPOSE: Replace the proposed effective mapping value manually. -->
<!-- @UX_FEEDBACK: Mapping method switches to manual override and prior warning may be cleared or recalculated. -->

<!-- [/DEF:ExecutionMappingReview:Component] -->

---

<!-- [DEF:CompiledSQLPreview:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: Present the exact Superset-generated compiled SQL preview with refresh state and failure diagnostics. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @UX_STATE: Missing -> Prompt user to generate preview. -->
<!-- @UX_STATE: Pending -> Show generation-in-progress feedback. -->
<!-- @UX_STATE: Ready -> Render read-only SQL preview with visible substitutions. -->
<!-- @UX_STATE: Stale -> Mark preview invalid after input changes until regenerated. -->
<!-- @UX_STATE: Error -> Show readable Superset compilation failure details and recovery action. -->
<!-- @UX_FEEDBACK: Refreshing preview updates timestamp and launch readiness cues. -->
<!-- @UX_RECOVERY: Users can navigate directly from preview error to the mapping or value row that caused failure. -->

#### ƒ **requestPreview**
<!-- @PURPOSE: Trigger preview generation for the current effective session inputs. -->

#### ƒ **showPreviewErrorTarget**
<!-- @PURPOSE: Focus remediation target when compilation diagnostics identify a mapping or variable issue. -->

<!-- [/DEF:CompiledSQLPreview:Component] -->

---

<!-- [DEF:LaunchConfirmationPanel:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: Summarize final run context, approvals, warnings, and compiled-preview status before dataset launch. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[DatasetReviewWorkspace] -->
<!-- @UX_STATE: Blocked -> Explicitly list missing gates preventing launch. -->
<!-- @UX_STATE: Ready -> Show final reviewed context and confirm action. -->
<!-- @UX_STATE: Submitted -> Show handoff to SQL Lab and audit snapshot reference. -->
<!-- @UX_FEEDBACK: Confirmation view is a contextual run summary, not a generic yes/no modal. -->
<!-- @UX_RECOVERY: When blocked, users can jump back to missing values, mapping approvals, or preview generation. -->

#### ƒ **buildLaunchSummary**
<!-- @PURPOSE: Project the exact run context into the final pre-launch summary. -->

#### ƒ **confirmLaunch**
<!-- @PURPOSE: Submit the run-ready launch request once all gates pass. -->

<!-- [/DEF:LaunchConfirmationPanel:Component] -->

---

## 3. Contract Coverage Notes

The feature requires:
- dedicated semantic resolution contracts instead of hiding source-ranking logic inside orchestration,
- a first-class clarification engine because guided ambiguity resolution is a persisted workflow, not a simple endpoint,
- a Superset extraction boundary distinct from preview/launch behavior,
- UI contracts that cover the UX state machine rather than only the happy path.

These contracts are intended to align directly with:
- [`specs/027-dataset-llm-orchestration/spec.md`](../spec.md)
- [`specs/027-dataset-llm-orchestration/ux_reference.md`](../ux_reference.md)
- [`specs/027-dataset-llm-orchestration/research.md`](../research.md)
- [`specs/027-dataset-llm-orchestration/data-model.md`](../data-model.md)