semantic

specs/027-dataset-llm-orchestration/contracts/modules.md

@@ -188,7 +188,7 @@ This document defines the semantic contracts for the core components of the Data
 # @LAYER: Infra
 # @RELATION: [DEPENDS_ON] ->[ImportedFilter]
 # @RELATION: [DEPENDS_ON] ->[TemplateVariable]
-# @RELATION: [DEPENDS_ON] ->[backend.src.core.superset_client.SupersetClient]
+# @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.
@@ -223,7 +223,7 @@ This document defines the semantic contracts for the core components of the Data
 # @LAYER: Infra
 # @RELATION: [DEPENDS_ON] ->[CompiledPreview]
 # @RELATION: [DEPENDS_ON] ->[DatasetRunContext]
-# @RELATION: [DEPENDS_ON] ->[backend.src.core.superset_client.SupersetClient]
+# @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.

specs/027-dataset-llm-orchestration/tests/reports/2026-03-17-report.md

@@ -0,0 +1,76 @@
+# Test Report: Superset Preview Pipeline Validation
+
+**Date**: 2026-03-17  
+**Executed by**: Tester Agent (Kilo Code)
+
+## Scope
+
+Validated the Superset preview pipeline fix set around:
+
+- preview compilation using the real [`/chart/data`](backend/src/core/superset_client.py) path
+- prevention of false dashboard-not-found semantics for non-dashboard preview 404 responses
+- preservation of the current API response contract in [`backend/src/api/routes/__tests__/test_dataset_review_api.py`](backend/src/api/routes/__tests__/test_dataset_review_api.py)
+
+## Files Changed
+
+- `backend/src/api/routes/__tests__/test_dataset_review_api.py`
+- `backend/src/core/__tests__/test_superset_preview_pipeline.py`
+
+## Coverage Added
+
+### API-level coverage
+
+In `backend/src/api/routes/__tests__/test_dataset_review_api.py`:
+
+- verifies preview endpoint still returns the existing preview DTO contract when preview compilation fails
+- verifies failed preview payload remains generic for non-dashboard 404 behavior
+- verifies error details mention the upstream resource path and do **not** regress into false dashboard-not-found wording
+
+### Core preview/network coverage
+
+In `backend/src/core/__tests__/test_superset_preview_pipeline.py`:
+
+- verifies [`SupersetClient.compile_dataset_preview`](backend/src/core/superset_client.py) calls the explicit chart-data endpoint
+- verifies compiled SQL is extracted from `result[].query`
+- verifies sync [`APIClient`](backend/src/core/utils/network.py) keeps non-dashboard 404s as generic [`SupersetAPIError`](backend/src/core/utils/network.py)
+- verifies sync [`APIClient`](backend/src/core/utils/network.py) still translates dashboard 404s into [`DashboardNotFoundError`](backend/src/core/utils/network.py)
+- verifies async [`AsyncAPIClient`](backend/src/core/utils/async_network.py) keeps non-dashboard 404s as generic [`SupersetAPIError`](backend/src/core/utils/network.py)
+- verifies async [`AsyncAPIClient`](backend/src/core/utils/async_network.py) still translates dashboard 404s into [`DashboardNotFoundError`](backend/src/core/utils/network.py)
+
+## Semantic Audit
+
+Ran workspace semantic audit through `axiom-core`.
+
+### Result
+
+- Workspace warnings: **1341**
+- Audit status for this task: pre-existing global semantic debt present across workspace
+- Targeted change set proceeded because no blocking semantic failure was isolated to the modified test scope
+
+## Test Commands Executed
+
+1. Initial direct targeted run:
+   - `cd backend && .venv/bin/python3 -m pytest src/api/routes/__tests__/test_dataset_review_api.py src/core/__tests__/test_superset_preview_pipeline.py -q`
+   - **Failed during collection**
+   - Cause: app import triggered DB init against local PostgreSQL
+
+2. Isolated targeted run with SQLite-backed env overrides:
+   - `cd backend && DATABASE_URL=sqlite:///./test_app.db TASKS_DATABASE_URL=sqlite:///./test_tasks.db AUTH_DATABASE_URL=sqlite:///./test_auth.db .venv/bin/python3 -m pytest src/api/routes/__tests__/test_dataset_review_api.py src/core/__tests__/test_superset_preview_pipeline.py -q`
+   - **Failed**
+   - Cause: two then one mismatched assertion(s) against actual [`DashboardNotFoundError`](backend/src/core/utils/network.py) message format
+
+3. Final rerun with same SQLite overrides:
+   - `cd backend && DATABASE_URL=sqlite:///./test_app.db TASKS_DATABASE_URL=sqlite:///./test_tasks.db AUTH_DATABASE_URL=sqlite:///./test_auth.db .venv/bin/python3 -m pytest src/api/routes/__tests__/test_dataset_review_api.py src/core/__tests__/test_superset_preview_pipeline.py -q`
+   - **Passed**
+
+## Final Test Result
+
+- Total targeted tests passed: **20**
+- Failed: **0**
+- Status: **PASS**
+
+## Notes / Remaining Limitations
+
+- The targeted API tests require temporary DB URL overrides because importing [`src.app`](backend/src/app.py) initializes the database eagerly through [`init_db()`](backend/src/core/database.py).
+- The semantic audit still reports substantial unrelated pre-existing workspace warnings.
+- This change set does not add direct unit tests for [`SupersetCompilationAdapter.compile_preview()`](backend/src/core/utils/superset_compilation_adapter.py); coverage is achieved indirectly through API failure-contract assertions plus direct client/network tests.