Query Doctor 0.11.0

Query Doctor 0.11.0 Release Notes

Release date: 2026-08-10
Package: query-doctor 0.11.0
Container image: ghcr.io/alexandrefimov/query-doctor:0.11.0
Release focus: Kubernetes-ready web deployment, container image support,
Helm chart support, synthetic Kubernetes self-test, raw-free deployment
readiness, health probes, one-profile web intake, persistent Recent profile
reuse, raw-free Online History, bounded Impala EXPLAIN artifact analysis, and
release-grade image validation

0.11.0 is the release where Query Doctor becomes practical to run as a
containerized web service. The Python package remains the primary local-first
operator tool, and Apache Impala remains the full production triage engine, but
the web UI now has a supported Docker image, Kubernetes deployment manifests,
a Helm chart, liveness/readiness probes, a bounded local/private one-profile web
upload path, and container CI.
It also adds a Kubernetes self-test Job, Helm test hook, and raw-free
deployment readiness summary for narrow cluster-side and pre-start confidence
checks.

The Query Inbox is now the primary web workflow for retained Recent results.
It combines raw-free Online History, bounded profile-job planning and worker
state, materialized Details snapshots, workload grouping, filters, and safe
view presets without turning browser refresh into synchronous profile, report,
optimizer, metadata SQL, or SQL-execution work.

This is not a hidden expansion of the security or engine boundary. Kubernetes
support means a supported web deployment starting point. It does not add native
authentication, authorization, sessions, RBAC, multi-tenant isolation, an
operator/CRD, arbitrary command running, SQL execution, or broader engine
support inside Query Doctor.

Kubernetes-Ready Web Deployment

• Added a root Dockerfile for the Query Doctor web UI.
• The image runs as fixed non-root UID/GID 10001:10001.
• The default image command starts the safe read-only synthetic demo:
  query-doctor-web --host 0.0.0.0 --port 8765 --allow-nonlocal-web-bind --public-demo.
• The image exposes port 8765 and includes a Docker healthcheck against
  /healthz.
• The image runs Query Doctor on supported Python 3.10 and includes Kerberos
  client tools plus the isolated
  /opt/query-doctor/.venv-impala-shell/bin/impala-shell runtime for
  configured Impala metadata refresh. Credentials, keytabs, ticket caches, and
  metadata coordinator settings still stay outside the image.
• The Helm chart can optionally run a configured-mode kerberos-kinit
  initContainer from an existing Secret and a bounded
  kerberos-ticket-renewer sidecar for the long-lived web pod. They write and
  refresh a shared ticket cache under /tmp/query-doctor-krb5/; the web
  container receives the cache and optional krb5.conf, not the principal or
  keytab. Finite collector and worker CronJobs continue to obtain one fresh
  ticket per Job instead of receiving a non-terminating sidecar.
• Added bounded staging smoke gates for one Kerberos cache refresh and one
  installed Online History collector/worker/operator-readiness cycle. The
  gates compare only raw-free status, cache timestamps, Job completion, image
  consistency, and allowlisted UI markers; they do not print tickets, Job logs,
  SQL, profiles, or retained page contents.
• Web deployments expose /deployment/readiness.json for a raw-free operator
  summary of mode, bind scope, source-type counts, probe endpoints, and safety
  boundary status.
• .dockerignore now excludes local configs, credentials, generated cases,
  reports, raw profiles, raw SQL, logs, caches, virtualenvs, and repository
  internals from the image build context.

Kubernetes Manifests

Kubernetes assets now live in deploy/kubernetes/.

• public-demo.yaml runs the read-only synthetic public demo with no
  credentials.
• The public-demo pod uses a non-root security context, drops Linux
  capabilities, disables service-account token mounting, uses a read-only root
  filesystem, mounts writable /tmp, and denies pod egress with a
  NetworkPolicy.
• configured-web.yaml is a private operator template for real configured
  web use. It mounts a Query Doctor config, reads credentials from a
  pre-created Kubernetes Secret, stores generated cases on a PVC, and exposes a
  ClusterIP Service plus example Ingress.
• Configured web pods use a heavier Recent-ready resource baseline than the
  public demo: 250m/512Mi requests and 2/2Gi limits.
• Non-local configured web binds use conservative Recent defaults unless the
  private config overrides them: profile analysis limit 50, overall Recent
  parallelism 4, metadata parallelism 2, and metadata top limit 10.
• Finished-query web Recent scans reuse already analyzed local cases when the
  Query ID matches a previous successful safe redacted batch output. Reused
  cases are copied into the new batch output, counted in the summary, and skip
  duplicate profile collection and deterministic analysis. Prior summaries must
  carry the same explicit profile reuse contract before artifacts are reused.
  Results coverage shows the aggregate reused-profile count, and a second
  submit for the same running finished Recent scan returns the existing job
  instead of launching duplicate collection.
• configured-web.yaml sets recent_batch_root to the dedicated temp-backed
  case-PVC cache mount, so configured Kubernetes deployments can preserve the
  finished-query Recent reuse cache across pod restarts without exposing raw
  SQL or raw profiles in trusted browser/report surfaces.
• Batch Recent can also write an optional local SQLite recent_history_db
  containing raw-free summary history for all discovered candidates. The store
  records bounded summary signals, selected/suspicion reason codes, and profile
  status without retaining raw SQL or profile text. --discover-only history
  runs also plan pending profile jobs for suspicious or selected summaries
  under the existing Recent profile budget. Batch summaries record only
  aggregate history-store status, summary count, and planned-job count.
• Configured web Query Inbox can render that retained history as a bounded
  read-only Online History view. It uses only raw-free summary fields, hides raw
  SQL/profile text/local store paths/raw artifact names, and keeps rows without
  materialized case artifacts read-only until a scan or profile worker creates
  Details artifacts. History-backed web refreshes use discover-only Recent
  scans, so they update retained summaries and profile-job planning without
  synchronous profile analysis, metadata SQL collection, LLM reports, optimizer
  jobs, generated SQL, or SQL execution.
• Helm configured installs can also render a disabled-by-default
  recentSummaryCollector CronJob for the same discover-only Recent planning
  loop against Postgres history. It writes retained summary rows and planned
  profile jobs plus a raw-free collector run summary without collecting
  profiles, running metadata SQL, LLM reports, optimizer jobs, or
  operator-readiness audits.
• Online History now overlays current Recent profile worker lifecycle state for
  retained rows, including pending, processing, retry-pending, analyzed, and
  failed. The Query Inbox status banner summarizes those states as aggregate
  profile-loop and Details-ready metrics. The status remains raw-free, keeps
  rows read-only until the analysis cache is materialized, and is not reset to
  not-collected by rediscovery.
• The same Online History banner now shows Recent summary collector freshness
  from the latest retained planning timestamp. This flags stale discover-only
  producers separately from profile-worker backlog health and derives safe
  next-step text without exposing Query IDs, source keys, local paths, raw
  collector payloads, or retained free-form text. Configured web installs can
  also point recent_history_collector_summary_json at a retained
  query_doctor_recent_history_collector_v1 summary so Query Inbox shows the
  producer's last allowlisted status, age, recorded-row, and planned-job
  counters while invalid or unsafe summaries degrade to safe status. Batch
  Recent mirrors the same allowlisted collector summary fields into optional
  --progress-jsonl events for recorded, disabled, warning, and failed
  producer states without exposing raw SQL, Query IDs, local paths, raw errors,
  or retained free-form text. Helm configured installs wire the scheduled
  recentSummaryCollector CronJob to retain that progress JSONL stream on the
  case PVC through recentSummaryCollector.progressJsonl, with chart
  validation keeping it under persistence.mountPath and separate from
  summaryJson.
• Configured Online History can also point
  recent_history_operator_readiness_summary_json at an already retained
  query_doctor_recent_history_operator_readiness_v1 summary. Query Inbox
  projects only allowlisted readiness, evidence, reason-code labels, schema,
  worker, and retention counters into the status banner. Invalid, wrong-kind,
  or unsafe summaries degrade to a safe blocked/unavailable status without
  exposing the configured path, raw JSON, raw SQL, profile text, local store
  paths, or raw artifact names.
• Analyzed Online History rows can now open a raw-free Details snapshot when
  the history store has a ready recent_analysis_cache payload linked through
  available fingerprint_only profile-artifact metadata. Rows without that
  materialized cache stay read-only. The snapshot includes only allowlisted
  score, recommendation, aggregate metadata coverage, and processing timing
  fields; it does not expose profile bytes, profile fingerprints, storage keys,
  local paths, LLM reports, optimizer jobs, generated SQL, or SQL execution.
• Batch Recent can also write the same raw-free summary history to Postgres by
  setting recent_history_backend=postgres. The DSN is read from a
  Secret/env-provided variable, not ...

Query Doctor 0.10.0

Query Doctor 0.10.0 Release Notes

Release date: 2026-07-01
Package: query-doctor 0.10.0
Release focus: official bounded local Trino production support, stronger
Impala production triage, and release-grade safety gates

0.10.0 is the release where Trino moves out of beta-only positioning into an
official supported product boundary: bounded local production support for the
raw-free web Trino lanes. Apache Impala remains the full production triage
engine. Trino is now supported for explicitly configured local retained-list
Recent diagnosis, one explicit Query ID diagnosis, raw-free materialized
Details, deterministic Python Report, and optimizer guidance over the
server-owned materialized cases created by those lanes.

That support claim is intentionally precise. 0.10.0 does not make Trino an
Impala-parity engine, does not add shared/broader Trino production triage, and
does not add Running scans, query-history crawling, product metadata
collection, LLM reports, Query Optimizer jobs, generated Trino SQL, or SQL
execution.

Trino Is Official, Bounded, And Raw-Free

• trino_support_mode=production is now the release-facing mode for local
  Trino production support. It removes the legacy beta label for the same
  bounded local lanes.
• trino_support_mode=beta remains available for existing local setups that
  still want the legacy Trino Beta label.
• Trino Recent performs one bounded retained pruned coordinator query-list read
  and then bounded pruned QueryInfo reads for selected rows.
• Trino One Query ID performs one bounded pruned QueryInfo read for one
  explicit query.
• Trino Details, deterministic Python Report, and optimizer guidance are
  available only over server-owned raw-free materialized web cases from those
  Trino lanes.
• Trino retained-list Recent accepts real coordinator rows that include
  errorCode and errorType, but those fields are scrubbed before normalized
  facts, browser output, Details, reports, or optimizer guidance.
• The web and backend release smokes validate configured Trino Recent plus One
  Query ID without printing Query IDs, coordinator URLs, auth references, local
  paths, or raw payloads, and without SQL execution.

Impala Remains The Full Production Triage Engine

• Recent scan remains the flagship workflow for production Impala triage.
• Cloudera Manager remains the full Recent discovery/profile/metrics/events
  provider for Impala workflows.
• Direct Impala daemon workflows remain bounded and explicit: Recent scans,
  Running scans, and one Known Query ID through daemon endpoints, without
  Cloudera Manager events and without SQL execution.
• Optional direct Impala compatibility probes continue to degrade safely when
  older clusters lack JSON profile, /profile_docs, or /admission?json
  endpoints.
• Optional Prometheus runtime summaries remain bounded context for explicitly
  configured direct Impala workflows.

Details, Reports, And Optimizer Guidance

• Details remains an analyst decision page: why the query deserves attention,
  where to inspect, what supported change direction to try, and how to verify a
  comparable rerun.
• Trino Details uses only typed materialized raw-free case facts.
• Trino Python Report is deterministic and validated over those same raw-free
  facts.
• Trino optimizer output is guidance only. It does not create Query Optimizer
  jobs, does not generate Trino SQL drafts, and does not execute SQL.
• Browser and trusted report surfaces continue to block raw SQL, raw profiles,
  raw metadata, local paths, secrets, command execution details, model/runtime
  internals, raw artifact filenames, Query IDs, coordinator URLs, auth
  references, and raw payloads.

Product And Documentation Positioning

• README, package metadata, docs index, architecture, roadmap,
  release-readiness, engine-support, demo, and Help wording now describe Query
  Doctor as Impala-first with official bounded local Trino production lanes.
• The Trino support gap matrix is the source of truth for what is supported,
  what remains preview/import-only, and what is explicitly unsupported.
• Support-gate audits pin the bounded Trino claim and keep broader/shared
  expansion gates visible instead of silently implying future support.
• Public demo and README first-user paths remain local-only, synthetic,
  read-only, and raw-free.
• Spark remains compact support only: no production Spark triage, Recent scans,
  Details/trusted report output, optimizer behavior, raw event-log handling, or
  Spark job execution.

Validation

The 0.10.0 release candidate was validated with:

• public release gate: full Python test suite, ruff, active-doc checks,
  Markdown links, public-doc audit, release-history shape check, demo pack
  generation, and public-release preflight;
• Trino release-readiness bundle: shared deployment boundary, product-surface
  boundary, support-gap matrix, active docs, focused Trino tests, local-config
  readiness, backend live smoke, and web UI smoke;
• package build and metadata checks for query_doctor-0.10.0 source and wheel
  distributions;
• clean-wheel README Quickstart smoke from an installed wheel;
• installed user-path smoke covering console help contracts, one-profile
  Quickstart, README Quickstart, report/pipeline/corpus paths, real web E2E,
  optimizer guidance, public demo generation, CM and direct Impala dry-runs,
  Trino compact and web paths, and Spark compact paths.

The Trino release-readiness run completed with backend and UI smokes green,
bounded coordinator reads only, no SQL execution, and no raw Query ID,
coordinator URL, auth reference, local path, or raw payload output.

Upgrade Notes

• Upgrade with pip install --upgrade query-doctor after 0.10.0 is published.
• Run query-doctor-self-test after upgrading.
• Use query-doctor-web --public-demo for the read-only synthetic demo.
• Use trino_support_mode=production for the official bounded local Trino
  production lanes.
• Keep trino_support_mode=beta only when you intentionally want legacy beta
  labels for existing local setups.

Query Doctor 0.9.0

Query Doctor 0.9.0 Release Notes

Release date: 2026-06-19
Package: query-doctor 0.9.0
Supported production diagnostic engine: Apache Impala
Release focus: web diagnostics, actionable safe errors, Trino Beta demo
coverage, and release validation depth

0.9.0 is an Impala-first product hardening release. It keeps Apache Impala as
the only production-supported diagnostic engine while making browser failures
more actionable, tightening scan workflow state, and adding bounded Trino Beta
demo and local-readiness coverage without promoting Trino to production triage.

Highlights

• Browser-visible failures now use structured safe error cards with reason
  codes, workflow stages, safe detail bullets, and next-step guidance for
  Recent, Running, Known Query ID, optimizer, reports, Trino Beta, Spark
  compact, public demo, startup config, and async job polling paths.
• Diagnose now asks for Engine before Source cluster. Source clusters are
  filtered by engine capability, so Trino Beta sources do not appear in Impala
  workflows and Impala-only sources do not block Trino Beta selection.
• Recent scan progress no longer marks profile collection green while
  profile collection is still running alongside analyzer scoring.
• Details-page optimizer actions are gated by deterministic rewrite
  eligibility. Unsupported or guidance-only cases show an unavailable reason
  instead of exposing a runnable action that later fails generically.
• Russian UI mode now localizes long diagnostic body text in Recent Findings
  and Details recommendations while keeping compact headers, table labels,
  badges, artifacts, and technical terms in English.
• Synthetic demo data now includes raw-free read-only Trino Beta demo cases.
  Demo startup avoids accidental default local config discovery when launched
  from an explicit synthetic batch summary.
• Installed-package release smokes now include Trino Beta web flows and the
  broader installed user-path matrix.

Web And Workflow Improvements

• Impala collection, metadata preflight, profile lookup, report, optimizer,
  TLS, and subprocess failures are classified into browser-safe reasons with
  operator-oriented next steps while hiding raw SQL, profiles, metadata,
  subprocess output, Query IDs, URLs, credentials, local paths, and runtime
  internals.
• Job links and polling URLs are built only from internal 32-hex job ids, so
  display-safe host aliases cannot become status or cancel endpoints.
• Recent-result filters, spill toggles, and workload follow-up links now use
  root-relative targets and keep working from job/error pages as well as from
  home and batch-result pages.
• CM Known Query ID collection preserves the validated Impala Query ID
  separator needed by Cloudera Manager profile/detail routes while still
  rejecting unsafe path shapes.
• Direct/profile evidence handling was broadened for profile format, source
  provenance, timing/resource facts, and bounded Recent backfill behavior.

Trino Beta Boundary

• Trino Beta web Recent can consume one bounded retained pruned coordinator
  query-list read and then selected pruned QueryInfo reads, rendering raw-free
  compact diagnosis only.
• Trino Beta One Query ID remains a bounded pruned QueryInfo diagnosis path.
• Trino Beta result pages explicitly mark Running, query-history crawling,
  metadata, Details/reports, optimizer behavior, generated SQL, SQL execution,
  and production support as blocked surfaces.
• New dev-only readiness and smoke tools validate Trino Beta static boundary,
  local config, optional live backend, installed package, and UI flows without
  printing local config values, Query IDs, coordinator URLs, auth references,
  local paths, raw payloads, or secrets.
• This release does not add Trino production support, metadata collection,
  Details/trusted report output, optimizer behavior, SQL generation, SQL
  execution, or broad coordinator history crawling.

Support Boundary

• Apache Impala remains the only production-supported diagnostic engine.
• Cloudera Manager remains the full Recent discovery/profile/metrics/events
  provider for Impala workflows.
• Direct Impala remains bounded to Recent scans, Running scans, and one
  explicit Known Query ID through impalad daemon endpoints, without Cloudera
  Manager events.
• Direct JSON profile, /profile_docs, and /admission?json probes remain
  optional compatibility surfaces. Missing old-cluster endpoints degrade to
  unknown or not-configured unless explicitly required.
• Spark remains bounded compact support only and is not promoted to production
  Spark triage, Recent scans, Details/trusted reports, optimizer behavior,
  broad live collection, raw event logs, SQL/plans, environment/log dumps, or
  Spark job execution.

Release Validation

The 0.9.0 release candidate is validated with the public release gate, full
test suite, package artifact checks, installed user-path smokes, installed
Trino Beta web smoke, and available bounded live smokes before publication.
The repeatable validation path is:

• PUBLIC_RELEASE=1 scripts/local_gate.sh
• pre-commit run --all-files
• python3 -m pytest -q
• python3 -m build
• python3 -m twine check dist/*
• python3 scripts/clean_wheel_quickstart_smoke.py --replace-work-dir
• python3 scripts/installed_readme_quickstart_smoke.py --bin-dir <installed-venv>/bin --replace-work-dir
• python3 scripts/installed_web_e2e_smoke.py --bin-dir <installed-venv>/bin
• python3 scripts/installed_impala_web_ui_exports_smoke.py --bin-dir <installed-venv>/bin
• python3 scripts/installed_trino_beta_web_smoke.py --bin-dir <installed-venv>/bin --replace-work-dir
• python3 scripts/installed_user_paths_smoke.py --bin-dir <installed-venv>/bin --replace-work-dir
• python3 scripts/index_install_quickstart_smoke.py --version 0.9.0 --replace-work-dir

Upgrade Notes

• Upgrade with pip install --upgrade query-doctor after 0.9.0 is published.

• Run query-doctor-self-test after upgrading to verify the installed package.

• Use query-doctor-web --public-demo for the read-only synthetic demo.

• For one exported Impala profile, run:

  query-doctor-analyze --profile-text <profile.txt> --out <corpus-dir>
  query-doctor-web --corpus-dir <corpus-dir>

  Add --query-id <id> only when the profile has neither a readable Query ID
  header nor a strict Impala Web UI filename.

Query Doctor 0.8.0

Query Doctor 0.8.0 Release Notes

Release date: 2026-06-15
Package: query-doctor 0.8.0
Supported production diagnostic engine: Apache Impala
Release focus: first-run reliability, installed user-path validation, and
shared-owner raw access hardening

0.8.0 is an Impala-first adoption and trust release. It keeps Apache Impala as
the only production-supported diagnostic engine, but broadens the validated
new-user path from "works in a checkout" to "works after pip install from a
package index".

Highlights

• README Quickstart is now validated from installed console scripts:
  query-doctor-self-test, query-doctor-analyze --profile-text, and
  query-doctor-web --corpus-dir.
• Exported Apache Impala text profiles downloaded from the Impala Web UI can be
  analyzed when the filename has the strict profile_<query-id-high>_<query-id-low>
  shape and the body lacks a readable Query ID header. Embedded, filename, and
  explicit Query IDs must still agree before a local case is written.
• query-doctor-web --corpus-dir starts without Cloudera Manager settings when
  the corpus already contains complete manual-profile cases, and the Diagnose
  page shows those exported profiles automatically without a search query.
• query-doctor-self-test gives users an installed-package confidence check
  using synthetic local data only. It does not require Cloudera Manager,
  Kerberos, direct impalad access, Prometheus, network collectors, or LLM calls.
• Package, release-gate, TestPyPI publish, and PyPI publish workflows expose
  the README Quickstart installed-wheel smoke as a standalone CI step, in
  addition to the broader installed user-path smoke.
• Release smoke scripts now fail early on stale explicit work directories and
  offer guarded --replace-work-dir cleanup for query-doctor-* workspaces.
• scripts/index_install_quickstart_smoke.py installs Query Doctor from a
  configured PyPI/TestPyPI-compatible index in a clean venv, checks that the
  package imports from that venv instead of the source checkout, and replays
  the README Quickstart.
• Local release validation now includes installed README, installed web E2E,
  installed user-path, generic web Recent, direct-Impala web Recent, Known
  Query ID, and Recent-to-Known smoke wrappers. These wrappers print only safe
  aggregate counters and redacted setup hints.

Web And Impala Workflow Improvements

• Recent and Running scans can honor a local query_type filter, exposed as an
  Advanced field only when configured.
• Web Recent scans now continue with bounded partial analysis when a broad
  Cloudera Manager discovery reaches the raw query-summary cap. The UI marks
  those results as partial and tells operators to reduce Search depth or add
  user, pool, or query-type filters for complete coverage.
• Empty Recent results now distinguish "no matching queries" from source
  failures such as Cloudera Manager timeouts, so a timed-out summary read no
  longer looks like proof that no queries exist.
• Recent scan progress now explains that broad Cloudera Manager discovery can
  take a minute, and browser polling surfaces a safe "Scan status unavailable"
  state if the local Query Doctor web server stops responding.
• Recent triage scoring suppresses stats-hygiene-only attention for
  sub-30-second queries, reducing noisy recommendations for very short queries.
• Known Query ID analysis now generates and validates the deterministic Python
  report as part of the explicit submit job.
• Known Query ID and Recent-to-Known smoke paths accept collected or partial
  metadata state and redact Query IDs, local paths, raw SQL, profiles, and
  metadata from child output.
• Details folds validated optimizer recommendations, manual optimizer guidance,
  or a safe link to a validated SQL draft into the same Recommended change
  area as deterministic analyzer action cards.
• Direct Impala Recent discovery ignores inconsistent daemon query-list
  end_time values that precede start_time, so fresh running SELECT queries
  are not dropped by stale completion timestamps.
• Metadata collection accepts metadata_kerberos_host_fqdn /
  --metadata-kerberos-host-fqdn for load-balanced Impala metadata endpoints
  that authenticate against a Kerberos host principal.

Trust And Access Hardening

• Non-local source_visibility=owner_raw now requires configured authenticated
  viewer identity. Missing, invalid, duplicate, service, or host-principal
  viewer identity fails closed for raw source access.
• Owner-raw source access has a global kill switch and safe request-id
  correlated audit lines that omit raw SQL, Query IDs, case IDs, query users,
  paths, header values, and secrets.
• Owner-only source viewing is isolated from trusted reports, handoff,
  download, and LLM paths. Default safe-mode browser pages and trusted reports
  still do not expose raw SQL, raw profile text, raw metadata, local paths,
  subprocess output, secrets, model names, runtime internals, or raw artifact
  filenames.
• Browser-visible subprocess failures can include allowlisted safe reason hints
  for common Recent setup failures while still hiding raw stdout and stderr.

Support Boundary

• Apache Impala remains the only production-supported diagnostic engine.
• Cloudera Manager remains the full Recent discovery/profile/metrics/events
  provider for Impala workflows.
• Direct Impala remains bounded to Recent scans, Running scans, and one
  explicit Known Query ID through impalad daemon endpoints, without Cloudera
  Manager events.
• Direct JSON profile, /profile_docs, and /admission?json probes remain
  optional compatibility surfaces. Missing old-cluster endpoints degrade to
  unknown or not-configured unless explicitly required.
• Trino and Spark remain bounded preview/compact surfaces only as documented in
  the engine support matrix. This release does not promote them to production
  triage, Recent scans, Details/trusted reports, optimizer behavior, broader
  live collection, or Query Doctor-generated SQL.

Release Validation

The 0.8.0 release candidate has been validated with the local public release
gate, package artifact checks, installed user-path smokes, and a bounded live
Cloudera Manager web Recent smoke. The repeatable validation path is:

• PUBLIC_RELEASE=1 scripts/local_gate.sh
• pre-commit run --all-files
• python -m pytest -q
• python -m build
• python -m twine check dist/*
• python scripts/clean_wheel_quickstart_smoke.py --replace-work-dir
• python scripts/installed_readme_quickstart_smoke.py --bin-dir <installed-venv>/bin --replace-work-dir
• python scripts/installed_web_e2e_smoke.py --bin-dir <installed-venv>/bin
• python scripts/installed_user_paths_smoke.py --bin-dir <installed-venv>/bin --replace-work-dir
• scripts/query-doctor-web-recent-smoke --cluster <cluster-id> --window-minutes <minutes> --limit <n> --allow-no-metadata

python scripts/index_install_quickstart_smoke.py \
  --version 0.8.0 \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  --replace-work-dir

python scripts/index_install_quickstart_smoke.py \
  --version 0.8.0 \
  --replace-work-dir

Upgrade Notes

• Upgrade with pip install --upgrade query-doctor after 0.8.0 is published.

• Run query-doctor-self-test after upgrading to verify the installed package.

• For one exported Impala profile, run:

  query-doctor-analyze --profile-text <profile.txt> --out <corpus-dir>
  query-doctor-web --corpus-dir <corpus-dir>

  Add --query-id <id> only when the profile has neither a readable Query ID
  header nor a strict Impala Web UI filename.

Query Doctor 0.7.0

Query Doctor 0.7.0 Release Notes

Release date: 2026-06-12
Package: query-doctor 0.7.0
Supported production diagnostic engine: Apache Impala
Release focus: one exported Impala profile to local diagnosis, installed-wheel
release gates, and trust hardening

0.7.0 is an Impala-first adoption and trust release. It adds a low-friction
entry path for one exported Apache Impala text profile while preserving the
local-first, raw-free browser contract. Cloudera Manager remains the full Recent
provider, and Apache Impala remains the only production-supported diagnostic
engine.

Highlights

• New users can start from one exported Impala text profile without Cloudera
  Manager, Kerberos, direct impalad access, Prometheus, network collectors, or
  an LLM.
• query-doctor-analyze --profile-text --out stages a redacted,
  collector-shaped local case from the Query ID embedded in the exported
  profile, writes deterministic analysis_facts.md and analysis.json, and
  analyzes the case without live collection. --query-id remains available for
  profile exports without a readable Query ID header.
• query-doctor-web can read a configured manual_profile_dir as a local
  profile inbox. Entering the matching Known Query ID stages and analyzes the
  profile through the same redacted path, then renders Details and Python
  reports from deterministic artifacts.
• The root README now gives a short one-profile Quickstart before the trust
  boundary details, then separates three first paths: one exported profile, the
  synthetic public demo, or a minimal read-only Cloudera Manager Recent scan.
• Package and release workflows now include an installed-wheel one-profile
  smoke. The smoke verifies CLI staging, manual-profile web analysis, Details
  rendering, validated Python report rendering, launch-directory default corpus
  behavior, and that generated cases are not written under site-packages.

Manual Profile Safety

• Manual-profile intake is text-only and local-directory based. Browser upload
  of raw profiles remains out of scope.
• Manual-profile staging always redacts through the collector-shaped profile
  path, derives the case Query ID from the profile header when available, and
  records whether an embedded Query ID was verified.
• Embedded Query ID mismatch fails closed before writing or replacing a case.
  Both Query ID: and Query (id=...) text forms are checked.
• Manual-only web configurations fail closed when the matching inbox file is
  missing instead of silently falling back to live collection.
• Browser-visible UI and trusted reports still do not render raw profile text,
  raw SQL, raw metadata, local paths, case directories, subprocess output,
  secrets, model names, runtime internals, or raw artifact filenames.

Web And Configuration

• query-doctor-web now accepts --corpus-dir, and config files accept
  corpus_dir. Relative config values resolve from the config file; relative
  CLI values resolve from the launch directory.
• When corpus_dir is unset, the web UI writes generated cases under
  ./cases/cm-corpus relative to the launch directory, including installed
  package runs. It no longer relies on the source tree or installed package
  directory.
• Startup and recovery messages now point one-profile users to
  manual_profile_dir, include the Query ID slug recipe for inbox files, and
  avoid circular incomplete-case remediation.
• Russian README and in-app Help now describe the manual-profile inbox path.

Trust And Analysis Hardening

• Added full-pipeline leak-canary coverage for manual-profile intake,
  deterministic analysis, scoring, report prompt assembly, trusted Python
  reports, and browser Details/report rendering.
• The leak-canary suite classifies generated sinks fail-closed and includes
  negative controls for unclassified sinks and disabled host redaction.
• Recent batch scoring now prefers typed analysis.json analyzer facts for
  core scoring components and records safe fallback labels when legacy rendered
  facts are still used.
• Query and stats optimization candidate scoring now prefer typed analyzer
  evidence from analysis.json for impact, opportunity, runtime signal, and
  metadata-gap inputs where the full contract is present.
• Renderer-to-parser characterization tests pin the legacy markdown contract
  while remaining rendered-facts consumers are migrated.
• Validated optimizer SQL drafts are now an explicit owner-local exception:
  Details shows them only when the current web source policy is
  source_visibility=owner_raw. The default source_visibility=safe path shows
  trusted recommendations/no-rewrite guidance instead, including when an older
  validated draft artifact is present.

Product Readiness

• Roadmap and customer-readiness docs now make the near-term adoption gate
  explicit: five external or design-partner Impala diagnostic runs with useful
  feedback.
• Public docs separate one-profile zero-trust fallback, synthetic public demo,
  and read-only Cloudera Manager Recent setup so users do not have to read the
  full engine preview knowledge base before first value.
• Partner-specific outreach copy and private validation evidence stay outside
  committed documentation.

Current Support Boundary

• Apache Impala remains the only production-supported diagnostic engine.
• Cloudera Manager remains the full Recent discovery/profile/metrics/events
  provider for Impala workflows.
• Direct Impala supports bounded Recent scans, Running scans, and one explicit
  Known Query ID through impalad daemon endpoints, without Cloudera Manager
  events.
• Direct JSON profile, /profile_docs, and /admission?json probes remain
  optional compatibility surfaces. Missing old-cluster endpoints degrade to
  unknown or not-configured unless the user explicitly requires that source.
• Optional Prometheus runtime metrics remain bounded direct-Impala context only
  when explicitly configured.
• Trino and Spark remain bounded preview/compact surfaces only as documented in
  the engine support matrix. This release does not promote them to production
  triage, Recent scans, Details/trusted reports, optimizer behavior, broader
  live collection, or Query Doctor-generated SQL.

Release Validation

The 0.7.0 release candidate should be validated with:

• PUBLIC_RELEASE=1 scripts/local_gate.sh
• pre-commit run --all-files
• python -m pytest -q
• python -m pytest -q tests/test_pyproject.py tests/test_installed_cli_contract.py tests/test_installed_one_profile_smoke.py
• python -m build
• python -m twine check dist/*
• python scripts/installed_one_profile_smoke.py --bin-dir <installed-venv>/bin
• TestPyPI install smoke before production PyPI publication

Upgrade Notes

• Upgrade with pip install --upgrade query-doctor after 0.7.0 is published.
• For the one-profile path, export one Apache Impala text profile, run
  query-doctor-analyze --profile-text <profile.txt> --out <case-dir>, or
  configure manual_profile_dir and enter the same Query ID in
  query-doctor-web. Add --query-id <id> only when the exported profile lacks
  a readable Query ID header.
• Regenerate the local demo pack with query-doctor-demo --out <demo-dir> --overwrite; use the printed QUERY_DOCTOR_ACTION_OUTCOMES_PATH value when
  launching query-doctor-web.
• Existing Impala workflows, configuration files, report safety rules, and
  optimizer trust boundaries remain compatible.

Query Doctor 0.6.0

Query Doctor 0.6.0 Release Notes

Release date: 2026-06-06
Package: query-doctor 0.6.0
Supported production diagnostic engine: Apache Impala
Release focus: bounded second-engine handoff gates and Impala diagnostic-loop
calibration

0.6.0 is a safety, support-boundary, and diagnostic-readiness release. Apache
Impala remains the only production-supported triage engine. Trino and Spark gain
stronger raw-free, bounded preview/compact handoff paths, but they still do not
become production product engines.

Highlights

• The public handoff history has been regrouped into reviewable semantic commits
  without changing the final tree.
• Impala diagnostic-loop audits now retain raw-free loop summaries, primary
  coverage gates, workload/action-outcome gates, stats readiness, optimizer
  funnel readiness, and north-star aggregate gates.
• Synthetic Impala gates now protect representative primary-bottleneck coverage,
  measured comparable-rerun action outcomes, and the combined north-star
  baseline. Remaining unknowns are classified by safe resolution class so clean
  or out-of-scope boundaries do not look like missing analyzer evidence.
• Workload/action-outcome feedback now requires comparable-rerun verification
  and measured results for tracked recommendation families before strict
  calibration gates pass.
• Shared engine intake now uses the redaction_note_v1 package-style safety
  contract for raw-free Trino and Spark evidence handoff paths.
• A machine-checkable engine capability manifest now pins adapter flags, bounded
  CLI roles, isolated preview web routes, dev-only handoff scripts, and product
  surface exclusions for Impala, Trino, and Spark.
• Shared handoff-artifact helpers now enforce safe JSON output, path-overlap
  checks, and safe relative retained-manifest references.

Trino Boundary

• Trino retained package-level handoff suites can require accepted source
  contracts, diagnostic-lane source granularities, and verification scopes
  without reopening raw packages or printing rejected user values.
• Trino compact diagnosis now emits a raw-free diagnostic-lane contract with
  source granularity, readiness, verification scope, supported-attention counts,
  fact-state counters, and product-surface audit requirements.
• Trino one-query handoff wrappers and retained suite audits now validate
  readiness summaries, handoff summaries, smoke summaries, product-surface
  summaries, duplicate artifact references, source contracts, and safe
  version-family breadth.
• Trino source-contract registry checks and aggregate metadata summary import
  are available as bounded raw-free preview surfaces only. Metadata summaries do
  not unlock live Trino metadata collection, Details, trusted reports,
  optimizer behavior, or generated Trino SQL.

Spark Boundary

• Spark is registered only for bounded compact support surfaces: compact History
  Server intake for one explicit application, compact evidence-package
  build/validation/fixture export, compact diagnosis, and strict local handoff
  readiness audits.
• Spark compact readiness, product-surface, support-boundary, and package
  handoff summaries now retain diagnostic-lane readiness, source-granularity,
  verification-scope, and fact-state counters.
• Spark one-application handoff wrappers can collect one bounded compact
  History Server application, write raw-free compact/diagnosis/boundary
  artifacts, retain suite manifests, and bridge accepted retained suites into
  sanitized compact evidence packages.
• Spark remains below production support. This release does not add Recent
  scans, Details or trusted-report output, optimizer behavior, broader live
  collection, raw event logs, raw SQL/plans, environment/log dumps, or Spark job
  execution.

Current Support Boundary

• Apache Impala remains the only production-supported diagnostic engine.
• Cloudera Manager remains the full Recent discovery/profile/metrics/events
  provider for Impala workflows.
• Direct Impala supports bounded Recent scans, Running scans, and one explicit
  Known Query ID through impalad daemon endpoints, without Cloudera Manager
  events.
• Direct JSON profile, /profile_docs, and /admission?json probes remain
  optional compatibility surfaces. Missing old-cluster endpoints degrade to
  unknown or not-configured unless the user explicitly requires that source.
• Optional Prometheus runtime metrics remain bounded direct-Impala context only
  when explicitly configured.

Safety And Publication Notes

• Web Recent scan and Running scan workflows still do not auto-run reports,
  LLM narratives, or optimizer jobs.
• Browser-visible UI and trusted reports still must not expose raw SQL, raw
  profiles, raw metadata, local paths, process logs, secrets, model names,
  runtime internals, or raw artifact filenames.
• Query Optimizer behavior remains read-only. Trusted SQL drafts still require
  Python-owned recipes, deterministic execution, and strict validation.
• Trino and Spark compact preview web routes remain isolated local pages. They
  are not Recent, Details, trusted-report, optimizer, or live Query ID product
  surfaces.
• README screenshot currency was reviewed for this release. Existing public
  screenshots still come from the synthetic demo pack and match the documented
  first-screen demo path.

Release Validation

The 0.6.0 release candidate should be validated with:

• PUBLIC_RELEASE=1 scripts/local_gate.sh
• pre-commit run --all-files
• python -m pytest -q
• python -m pytest -q tests/test_pyproject.py
• python -m build
• python -m twine check dist/*
• public-release preflight with history scanning against the reviewable release
  branch
• synthetic demo pack generation and README screenshot provenance review

Upgrade Notes

• Upgrade with pip install --upgrade query-doctor after 0.6.0 is published.
• Regenerate the local demo pack with query-doctor-demo --out <demo-dir> --overwrite; use the printed QUERY_DOCTOR_ACTION_OUTCOMES_PATH value when
  launching query-doctor-web.
• Existing Impala workflows, configuration files, report safety rules, and
  optimizer trust boundaries remain compatible.

Query Doctor 0.5.0

Query Doctor 0.5.0 Release Notes

Release date: 2026-06-04
Package: query-doctor 0.5.0
Supported production diagnostic engine: Apache Impala
Release focus: deterministic diagnostic-loop hardening and raw-free evidence
handoff gates

0.5.0 is a safety and diagnostic-readiness release. It keeps Apache Impala as
the only production-supported triage engine while hardening the local-first
diagnostic loop, selected-case action contracts, release gates, and private
preview evidence handoff paths.

Highlights

• Recent Details recommendations now keep an analyst decision path: why the
  query deserves attention, where to inspect, what supported change direction
  to try, and how to verify with a comparable rerun.
• Query-shape and stats action cards now fail safe when older candidate data
  lacks comparable-rerun wording. Medium or High recommendations cannot render
  as EXPLAIN-only follow-ups.
• Stats optimization scoring now requires a complete evidence chain before a
  candidate can become Medium or High. Partial metadata plus estimate mismatch
  is no longer actionable unless supported missing or incomplete stats evidence
  is present.
• Representative Impala loop audits now include Details, trusted report
  revalidation, trusted optimizer artifacts, profile-evidence gates,
  diagnostic coverage, workload readiness, stats readiness, and optimizer
  funnel checks.
• Trusted optimizer artifact auditing now distinguishes trusted SQL drafts,
  trusted recommendations-only output, trusted no-rewrite output, and
  partial/untrusted artifacts without printing SQL, paths, filenames, or case
  identifiers.
• Workload diagnostics now share one action contract across queue and detail
  views, including verification metrics and local action-outcome feedback.
• Public release gates now include branch-history shape checks, current-tree
  public-safety scans, fixture provenance checks, README screenshot provenance,
  and stricter release-facing documentation audits.

Private Preview And Research Boundaries

• Trino remains private-preview groundwork only. 0.5.0 adds stricter raw-free
  handoff gates for sanitized evidence packages, one-query pruned QueryInfo
  imports, compact diagnosis JSON, source-version requirements, smoke summaries,
  and retained handoff-suite manifests. These paths do not create public Trino
  engine support, live Recent scans, live Query ID product diagnosis, Details or
  trusted-report output, optimizer behavior, metadata collection, or generated
  Trino SQL.
• Spark compact History Server and evidence-package paths remain experimental
  contract-shaping surfaces. 0.5.0 adds package readiness verdicts, compact
  diagnosis boundary drift checks, fixture export manifests, strict handoff
  audits, and optional raw-free machine summary JSON for handoff readiness.
  These paths do not create public Spark engine support, Recent scans, Details
  or trusted-report output, optimizer behavior, raw event-log handling, raw
  SQL/plan display, environment/log dumps, or Spark job execution.
• Normalized engine facts remain a raw-free contract seam. They are not the
  product engine registry and do not replace the production Impala analyzer,
  presenter, report, or optimizer facts.

Current Support Boundary

• Apache Impala remains the only production-supported diagnostic engine.
• Cloudera Manager remains the full Recent discovery/profile/metrics/events
  provider for Impala workflows.
• Direct Impala supports bounded Recent scans, Running scans, and one explicit
  Known Query ID through impalad daemon endpoints, without Cloudera Manager
  events.
• Direct JSON profile, /profile_docs, and /admission?json probes remain
  optional compatibility surfaces. Missing old-cluster endpoints degrade to
  unknown or not-configured unless the user explicitly requires that source.
• Optional Prometheus runtime metrics remain bounded direct-Impala context only
  when explicitly configured.

Safety And Publication Notes

• Web Recent scan and Running scan workflows still do not auto-run reports,
  LLM narratives, or optimizer jobs.
• Browser-visible UI and trusted reports still must not expose raw SQL, raw
  profiles, raw metadata, local paths, process logs, secrets, model names,
  runtime internals, or raw artifact filenames.
• Query Optimizer behavior remains read-only. Trusted SQL drafts still require
  Python-owned recipes, deterministic execution, and strict validation.
• Report validators now have broader adversarial English/Russian coverage for
  unsupported causal wording, stale-statistics claims, stats-maintenance
  overclaims, row/cardinality estimate direction wording, and inline SQL-like
  prose.
• Browser/log host redaction now uses a linear scanner for free-text FQDNs,
  host-like single-label names, and bare host:port values, preserving stable
  aliases while removing a CodeQL polynomial-regex risk.
• README screenshot currency was reviewed for this release. Existing public
  screenshots still come from the synthetic demo pack and match the documented
  first-screen demo path.

Release Validation

The 0.5.0 release candidate should be validated with:

• PUBLIC_RELEASE=1 scripts/local_gate.sh
• pre-commit run --all-files
• python -m pytest -q
• python -m pytest -q tests/test_pyproject.py
• python -m build
• python -m twine check dist/*
• public-release preflight with history scanning against the reviewable release
  branch
• synthetic demo pack generation and README screenshot provenance review

Focused pre-release Impala checks for this candidate included representative
raw-free Details and stats audits over a retained sanitized Recent summary. The
aggregate loop still tracks remaining calibration work for profile classifier
parity, diagnostic coverage thresholds, and optimizer mixed-track grouping; that
work remains post-0.5.0 diagnostic-loop hardening rather than a release blocker.

Upgrade Notes

• Upgrade with pip install --upgrade query-doctor after 0.5.0 is published.
• Regenerate the local demo pack with query-doctor-demo --out <demo-dir> --overwrite; use the printed QUERY_DOCTOR_ACTION_OUTCOMES_PATH value when
  launching query-doctor-web.
• Existing Impala workflows, configuration files, report safety rules, and
  optimizer trust boundaries remain compatible.

Query Doctor 0.4.3

Query Doctor 0.4.3 updates the web decision flow for Python vs LLM reports and optimizer availability, polishes Details/New scan UX, and prepares the package metadata for the 0.4.3 release.

Query Doctor 0.4.2

Query Doctor 0.4.2 Release Notes

Release date: 2026-06-01
Package: query-doctor 0.4.2
Supported production diagnostic engine: Apache Impala
Release focus: public release baseline and release-boundary hardening

0.4.2 is a safety and release-boundary hardening release. It keeps the 0.4.1
synthetic demo and product behavior, while tightening public fixture hygiene,
release validation, documentation boundaries, and repository hardening.

Highlights

• Public fixtures and tests consistently use synthetic schema, column, user,
  host, Kerberos cache, and Query ID examples.
• Public documentation now has a clearer boundary between durable project docs
  and maintainer-local operational notes.
• The web Recent scan timezone default and canonical example config now use
  UTC; existing configs can keep any explicit IANA timezone.
• CI runs public-safety documentation checks and the full public-release
  preflight.
• Release preparation includes public documentation audits, focused
  safety/demo/docs tests, package checks, and the public-release guard.

Current Support Boundary

• Apache Impala remains the only implemented and supported production engine.
• Cloudera Manager remains the full Recent discovery/profile/metrics/events
  provider for Impala workflows.
• Direct Impala remains limited to bounded Recent scans, Running scans, and one
  Known Query ID through impalad daemon endpoints, with optional bounded
  Prometheus runtime metrics when explicitly configured.
• Trino remains private-preview groundwork only. It is not a public engine
  selector, live collector, browser/report surface, optimizer workflow,
  metadata collector, query-history reader, or generated query-text path.

Safety And Publication Notes

• Browser-visible UI and trusted reports still must not expose raw SQL, raw
  profiles, raw metadata, local paths, process logs, secrets, model names,
  runtime internals, or raw artifact filenames.
• Public source releases start at 0.4.2. Use package-index artifacts for older
  installed-version compatibility testing when needed.
• Release automation continues to use GitHub OIDC Trusted Publishing through
  maintainer-approved pypi and testpypi environments.

Release Validation

The 0.4.2 release candidate was validated with:

• query-doctor-demo-preflight --public-release.
• Focused public-safety, demo-preflight, and documentation tests.
• Package build and metadata checks.
• Public documentation audit, active-document check, markdown link check, and
  git diff --check.

Upgrade Notes

• Upgrade with pip install --upgrade query-doctor after 0.4.2 is published.
• Regenerate the local demo pack with query-doctor-demo --out <demo-dir> --overwrite; use the printed QUERY_DOCTOR_ACTION_OUTCOMES_PATH value when
  launching query-doctor-web.
• Existing Impala workflows, configuration files, report safety rules, and
  optimizer boundaries are unchanged.