[mikebridge]

SUMMARY

Builds on #45553; review that first. This PR includes its commits until it merges.

TL;DR: Give providers explicit credential readiness and a typed backend-failure contract.

Background and problem: Semantic providers currently have to recognize the host's secret placeholder to decide whether schema discovery is safe, and lack an SDK error for backend execution faults. This change adds a required SemanticCredentialReadiness enum to both schema hooks and a fixed-message SemanticBackendError.

What this changes: The host derives readiness from raw configuration before partial validation can discard unresolved fields. Preview payloads cannot assert readiness or recover saved credentials. Transport errors are reconstructed from validated failure/status fields and a freshly sanitized label; subclass formatters cannot supply public text. Typed backend failures return generic guidance without logging their causes or tracebacks. Unknown exceptions retain their type at ERROR and full diagnostic chain at DEBUG in server logs only.

Host and provider schema overrides must upgrade together. UPDATING.md and the provider author guide describe the required arguments and error contract. The translation template also includes two strings already introduced by the transport prerequisite.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

Not applicable: SDK and backend boundary changes only.

TESTING INSTRUCTIONS

With the repository Python environment and local superset-core/src on PYTHONPATH:

CI=1 PYTHONPATH=.:superset-core/src python -m pytest -q -o addopts= \
  tests/unit_tests/semantic_layers superset-core/tests \
  tests/unit_tests/mcp_service/test_tool_inventory.py \
  tests/unit_tests/mcp_service/test_chart_tool_inventory.py \
  tests/unit_tests/mcp_service/test_mcp_tool_registration.py \
  tests/unit_tests/mcp_service/test_native_tool_surface.py \
  tests/unit_tests/mcp_service/semantic_layer/tool/test_get_table.py
CI=1 PYTHONPATH=.:superset-core/src python -m pytest -q -o addopts= \
  tests/unit_tests/commands/semantic_layer
python scripts/translations/check_pot_drift.py

Final candidate results: 1,958 semantic-layer tests passed at 100.00% coverage, 635 supplemental SDK/command/network/MCP tests passed, and 13 SDK conformance tests passed. Changed-file pre-commit (including MyPy) passed; POT drift passed before the merge. The independent macOS export run needed a test-only sentinel rename because the word "private" also matches /private/tmp traceback paths; the author checkout passed unchanged. This test portability follow-up remains open. Added cases cover masked nested preview configuration, spoofed readiness, saved-runtime authority, required SDK arguments, safe transport errors, suppressed sensitive causes, chart cache admission, values lookup and the MCP error envelope.

No live provider or deployment validation is claimed. Provider schema overrides must be updated together with the host.

Follow-ups: prove each provider blocks discovery for unresolved readiness; consider rejecting literal secret placeholders during create/import; validate status fields in the transport SDK constructor in addition to host boundary validation. Also make malformed transport-error handling explicit at metadata endpoints so it does not rely on the outer error wrapper and produce an extra host-only ERROR traceback. These follow-ups are not implemented by this PR.

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags: existing SEMANTIC_LAYERS
• Changes UI
• Includes DB Migration
• Introduces new feature or API: required SDK readiness keyword and backend error type
• Removes existing feature or API

[codecov]

Codecov Report

❌ Patch coverage is 97.46835% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.78%. Comparing base (7f2b04f) to head (09b8d45).
⚠️ Report is 6 commits behind head on master.

Files with missing lines	Patch %	Lines
superset/utils/network.py	89.79%	5 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #45554      +/-   ##
==========================================
+ Coverage   84.73%   84.78%   +0.04%     
==========================================
  Files        3069     3075       +6     
  Lines      205819   206892    +1073     
  Branches    48408    48475      +67     
==========================================
+ Hits       174403   175409    +1006     
- Misses      28122    28179      +57     
- Partials     3294     3304      +10     

Flag	Coverage Δ
hive	34.48% <30.37%> (-0.02%)	⬇️
mysql	52.53% <31.89%> (?)
postgres	52.55% <31.89%> (-0.06%)	⬇️
presto	36.20% <30.37%> (-0.03%)	⬇️
python	87.79% <97.46%> (+0.03%)	⬆️
sqlite	52.30% <31.89%> (-0.07%)	⬇️
superset-extensions-cli	91.24% <ø> (?)
unit	82.57% <97.46%> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[netlify]

✅ Deploy Preview for superset-docs-preview ready!

Name	Link
🔨 Latest commit	09b8d45
🔍 Latest deploy log	https://app.netlify.com/projects/superset-docs-preview/deploys/6ae55a73c59ce91c75ded705
😎 Deploy Preview	https://deploy-preview-45554--superset-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.