463 lines
24 KiB
Markdown
463 lines
24 KiB
Markdown
# 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) |