busya
7c85552132
Move dataset review clarification into the assistant workspace and rework the review page into a chat-centric layout with execution rails. Add session-scoped assistant actions for mappings, semantic fields, and SQL preview generation. Introduce optimistic locking for dataset review mutations, propagate session versions through API responses, and mask imported filter values before assistant exposure. Refresh tests, i18n, and spec artifacts to match the new workflow. BREAKING CHANGE: dataset review mutation endpoints now require the X-Session-Version header, and clarification is no longer handled through ClarificationDialog-based flows
497 lines
27 KiB
Markdown
497 lines
27 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]
|
||
# @RELATION: [EXPOSES_STATE_TO] ->[AssistantApi]
|
||
# @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 mixed-initiative clarification sessions, including prioritized agent prompts, answer persistence, assistant routing, and readiness impact updates.
|
||
# @LAYER: Domain
|
||
# @RELATION: [DEPENDS_ON] ->[ClarificationSession]
|
||
# @RELATION: [DEPENDS_ON] ->[ClarificationQuestion]
|
||
# @RELATION: [DEPENDS_ON] ->[ClarificationAnswer]
|
||
# @RELATION: [DEPENDS_ON] ->[ValidationFinding]
|
||
# @RELATION: [DISPATCHES] ->[AssistantChatPanel]
|
||
# @PRE: target session contains unresolved or contradictory review state.
|
||
# @POST: every recorded answer updates the clarification session and associated session state deterministically, and the next agent prompt is routable through assistant chat.
|
||
# @SIDE_EFFECT: creates clarification questions, persists answers, updates findings/profile state, emits assistant-routable clarification prompts.
|
||
# @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 for assistant-chat delivery.
|
||
|
||
#### ƒ **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, assistant-chat clarification, preview, and launch UX. -->
|
||
<!-- @LAYER: UI -->
|
||
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
|
||
<!-- @RELATION: [BINDS_TO] ->[AssistantApi] -->
|
||
<!-- @RELATION: [BINDS_TO] ->[AssistantChatPanel] -->
|
||
<!-- @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 assistant-led clarification thread 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, task state derivation, and assistant/workspace focus synchronization. -->
|
||
<!-- @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:AssistantChatPanel:Component] -->
|
||
<!-- @COMPLEXITY: 4 -->
|
||
<!-- @PURPOSE: Provide the mixed-initiative assistant drawer for clarification, free-form dataset questions, contextual actions, and confirmation cards tied to the active dataset review session. -->
|
||
<!-- @LAYER: UI -->
|
||
<!-- @RELATION: [DEPENDS_ON] ->[AssistantApi] -->
|
||
<!-- @RELATION: [BINDS_TO] ->[DatasetReviewWorkspace] -->
|
||
<!-- @RELATION: [BINDS_TO] ->[ClarificationEngine] -->
|
||
<!-- @UX_STATE: Idle -> Drawer is closed or shows starter prompts for the active session. -->
|
||
<!-- @UX_STATE: ClarificationQueue -> Assistant presents the next prioritized clarification prompt with suggested answers. -->
|
||
<!-- @UX_STATE: Freeform -> User asks context questions about filters, findings, mappings, or SQL preview state. -->
|
||
<!-- @UX_STATE: NeedsConfirmation -> Chat renders confirmation cards for dangerous or audit-relevant actions. -->
|
||
<!-- @UX_STATE: Error -> Drawer preserves session context and shows retry guidance without hiding the workspace. -->
|
||
<!-- @UX_FEEDBACK: Context actions and assistant prompts highlight the referenced workspace filter, field, mapping, or finding. -->
|
||
<!-- @UX_RECOVERY: Users can skip, defer, resume, or abandon a clarification thread without losing session state. -->
|
||
|
||
#### ƒ **submitSessionScopedMessage**
|
||
<!-- @PURPOSE: Send a free-form or guided assistant message bound to the active dataset review session. -->
|
||
|
||
#### ƒ **renderConfirmationCard**
|
||
<!-- @PURPOSE: Present assistant-driven confirmation UI for state-changing actions such as mapping approval, preview generation, or launch. -->
|
||
|
||
#### ƒ **highlightWorkspaceTarget**
|
||
<!-- @PURPOSE: Synchronize assistant focus with the referenced workspace element. -->
|
||
|
||
<!-- [/DEF:AssistantChatPanel:Component] -->
|
||
|
||
---
|
||
|
||
<!-- [DEF:AssistantApi:Module] -->
|
||
<!-- @COMPLEXITY: 4 -->
|
||
<!-- @PURPOSE: Accept session-scoped assistant messages and route grounded dataset-review intents to orchestration contracts without bypassing approval gates. -->
|
||
<!-- @LAYER: UI -->
|
||
<!-- @RELATION: [DEPENDS_ON] ->[DatasetReviewOrchestrator] -->
|
||
<!-- @RELATION: [DEPENDS_ON] ->[ClarificationEngine] -->
|
||
<!-- @RELATION: [DEPENDS_ON] ->[DatasetReviewSessionRepository] -->
|
||
<!-- @PRE: Assistant requests are authenticated and may include an active dataset review session identifier. -->
|
||
<!-- @POST: Responses stay grounded in the current session context and return deterministic confirmation or action states for frontend rendering. -->
|
||
<!-- @SIDE_EFFECT: Reads session state, may dispatch approved orchestration commands, and records assistant interaction outcomes through existing audit pathways. -->
|
||
|
||
#### ƒ **handleSessionScopedMessage**
|
||
<!-- @PURPOSE: Load active dataset review context and answer or route a user assistant message against that session. -->
|
||
|
||
#### ƒ **dispatchDatasetReviewIntent**
|
||
<!-- @PURPOSE: Route approved dataset-review commands such as mapping approval or preview generation to orchestration services. -->
|
||
|
||
<!-- [/DEF:AssistantApi:Module] -->
|
||
|
||
---
|
||
|
||
<!-- [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] -->
|
||
|
||
---
|
||
|
||
### Retired Contract: `ClarificationDialog`
|
||
|
||
`ClarificationDialog` is retired for feature 027 rebaseline. Its responsibilities move into `AssistantChatPanel`, which now owns clarification presentation, free-form dataset questions, and confirmation-card interactions inside the global assistant drawer.
|
||
|
||
---
|
||
|
||
<!-- [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)
|