qplotter 1.6.0b3__tar.gz → 1.6.2__tar.gz

{qplotter-1.6.0b3 → qplotter-1.6.2}/CHANGELOG.md

@@ -2,16 +2,137 @@
 
 All notable user-facing changes are recorded here.
 
-Historical releases used GitHub source tags. The prepared split beta uses the
-PyPI distributions `qplotter` and `qplotter-native`; publication requires the
-release workflow and its validation gates. See `docs/distribution.md`.
+## 1.6.2 — Unreleased
 
-## Unreleased
+This bugfix release improves measurement correctness, live viewing and plot
+lifecycle reliability. The native dependency remains `qplotter-native==1.0.1`.
+
+### Fixed
+
+- Load inferred QCoDeS parameters and missing ancillary array cells, preserving
+  recorded samples across previews, plotting, incremental refresh and raw CSV.
+- Handle singleton and empty array acquisitions consistently, including planned
+  scan shapes, and check expanded memory requirements before allocating them.
+- Preserve extended floating-point and integer precision in derivatives, FFTs,
+  clipping, centering, statistics, heatmaps, previews and CSV exports.
+  Honor finite clipping bounds on float16/float32 measurement arrays.
+- Preserve axis meaning and source ownership during mixed-plot promotion,
+  cut refresh and drag-and-drop; refresh retained sources while paused and
+  cancel pending work when its target window closes.
+- Avoid Qt callback errors when reassigning axes on a clipped trace, and clear
+  obsolete omission warnings when live metadata becomes available again.
+- Honor accepted reader cancellation and delayed helper cancellation without
+  publishing stale results or unnecessarily retiring healthy readers.
+- Refresh live-reader schema descriptions when QCoDeS adds metadata, so newly
+  acquired runs expose their current columns without missing data or query errors.
+- Protect measurement files from diagnostic-log reuse and synthetic generation
+  side effects; report malformed generator inputs and profiling failures cleanly.
+  Retire benchmark plot windows before Qt application teardown.
+- Allow qPlot to start when the diagnostic log path contains a symlink loop.
+
+### Compatibility and validation
+
+- Standard QCoDeS main-database storage remains supported. Runs using the
+  optional separate-per-dataset storage backend are refused before opening
+  their measurement files, since safe multi-file live viewing is not implemented.
+- Main databases, WAL files and rollback journals remain physically read-only.
+  Only the pinned native reader may modify the exact colocated SHM file.
+- Add regression coverage and independently reviewed fixes documented in
+  `BUG_HUNT.md`. No legacy settings migrations are introduced. This draft does
+  not publish a release.
+
+## 1.6.1
+
+This patch release improves live acquisition viewing and release validation.
+
+### Fixed
+
+- Restore Auto-plot in trusted live mode. Newly detected runs open automatically,
+  and enabling Auto-plot opens the newest incomplete run. Requests survive
+  selection changes and refreshes, retry while run metadata becomes available,
+  and cancel when Auto-plot is disabled, the database changes, or qPlot closes.
+- Reduce unnecessary WAL coordination overhead that could cause deferred QCoDeS
+  writes to fail with `SQLITE_BUSY` during live viewing. Existing database
+  protections remain enforced.
+- Display the main window title as `qPlot - <version>` without a duplicated
+  application-name suffix.
+- Correct editable-install validation for source checkouts without generated
+  build metadata.
+
+### Maintenance
+
+- Release the native-reader fix as `qplotter-native==1.0.1`, installed
+  automatically by the application's updated dependency pin.
+- Add a workflow to revalidate published releases against their original
+  artifacts, retaining each release's original native dependency pin.
+- Update live-reader, Auto-plot, and release-validation documentation and add
+  README badges.
+
+## 1.6.0
+
+### Highlights ###
+
+- More improvements in handling large databases and datasets.
+- Multiple heatmaps and traces can share the same plot window.
+- Program now installs as a PyPi distribution for the first time, instead of via GitHub source tags.
+- Numerous small improvements to the UI.
+- Numerous bugs found by Codex Astra have been fixed. In particular, Codex now claims to rigorously enforce the rule that the database will never be modified by `qplot`. After about 30 rounds of automated bug searches, the last two rounds uncovered no bugs.
+- To implement this database safety, the installation contains a small C extension 'qplotter-native' for reading live databases through SQLite.
+
+### Main changes since 1.5.0
+
+(Everything in this section is AI-generated)
+
+- Read supported local QCoDeS databases live without copying the whole
+  database. Main database, WAL, and rollback-journal handles remain physically
+  read-only; SQLite may update only the exact colocated SHM coordination file.
+  Reader work is bounded and cancellable.
+- Load run metadata, thumbnails, previews, and explicit plots progressively,
+  prioritising selected and visible runs. Show clearer plot-loading progress
+  and keep cancellation, database switching, and shutdown responsive.
+- Combine line traces and heatmaps in one plot, with axis-aware drag-and-drop,
+  shared appearance controls, and source annotations included in exports.
+- Add system printing, configurable heatmap display grid limits, optional saved
+  run-table columns, plot tiling, cursor precision, and version/build information
+  in Help -> About qPlot and the main window title.
+- Improve QCoDeS variable-shaped array support, missing-data handling, numerical
+  precision, native transforms, averaging, autoscaling, and live run refresh.
+  Reject drawing ranges that cannot faithfully represent recorded values.
+- Fix CSV alignment and precision, standalone-measurement exports, SVG output,
+  and PDF publication. Strengthen protection against auxiliary outputs
+  overwriting database files and against blocking special-file inputs.
+- Split the application into `qplotter` and the separately versioned
+  `qplotter-native==1.0.0`. Supported installations use prebuilt native wheels
+  without a compiler; imports and commands remain `qplot`. Release validation
+  covers CPython 3.11-3.14, Windows x64, macOS ARM64/Intel, and headless Linux
+  x86_64. Windows and macOS remain the supported desktop platforms.
+- Strengthen application/helper shutdown and settings recovery, and save
+  configuration changes transactionally.
+
+### Upgrading
+
+- Older or incompatible settings are reset to current defaults. Settings
+  migration is not supported.
+- The old `qplot` distribution and `qplotter` share imports and commands and
+  must not coexist. Prefer a fresh virtual environment, or follow the removal
+  and reinstall instructions in `docs/distribution.md`.
+- This entry is draft release text. Publication still requires the tagged
+  release workflow and all validation gates; this PR does not publish packages.
 
 ## 1.6.0b3 - Unreleased
 
 ### Added
 
+- Combine line traces and heatmaps in one plot, with axis-aware preview drops
+  and a shared Appearance dialog. Removing the original dataset promotes a
+  remaining source while retaining the plot's appearance and state.
+- Identify plotted databases, run IDs, and parameters in a shaded annotation
+  strip included in exports. A saved Show source annotation preference controls
+  visibility and is enabled by default.
+- Add saved plot-tiling and cursor-precision preferences, and limit the graph
+  font-size preference to graph text.
+- Add Help -> About qPlot with the running version, source commit and local
+  changes, plus commit and PR provenance in CI-built application packages.
 - Split pure-Python application distribution `qplotter` from native reader
   distribution `qplotter-native`, retaining the qPlot name, `qplot` imports and
   commands. Ordinary and editable application installation use prebuilt native
@@ -22,6 +143,9 @@ release workflow and its validation gates. See `docs/distribution.md`.
 
 ### Changed
 
+- Consolidate plot feedback and loading progress in the refresh toolbar, with
+  accurate initial point counts and stable cursor readouts.
+- Clarify refresh controls and incompatible-axis confirmations.
 - Load and refresh explicit plots through the trusted, physically read-only
   reader without copying the whole database. Small runs can open while a large
   run is loading, including with a single processing thread.
@@ -33,6 +157,13 @@ release workflow and its validation gates. See `docs/distribution.md`.
   exact source dimensions are not retained during downsampling. Right-align
   resolution information while keeping cursor coordinates left-aligned.
 
+### Fixed
+
+- Preserve coordinate ownership, drawing order, native transforms, and specific
+  FFT validation messages when combining or replacing plot sources.
+- Stabilize GUI test waits and release plot windows and background workers
+  during teardown.
+
 ## 1.6.0b1 - 2026-09-28
 
 ### Added

{qplotter-1.6.0b3 → qplotter-1.6.2}/CONTRIBUTING.md

@@ -52,7 +52,7 @@ Linux is exercised in headless CI; Windows and macOS are supported desktop
 platforms. See the [platform matrix](docs/distribution.md#supported-platforms).
 
 The root distribution `qplotter` is pure Python. Install the compatible
-`qplotter-native==1.0.0` platform wheel with the application in editable
+`qplotter-native==1.0.1` platform wheel with the application in editable
 mode. After the native release is on PyPI, no separate download is needed:
 
 ```console

{qplotter-1.6.0b3 → qplotter-1.6.2}/MANIFEST.in

@@ -27,6 +27,7 @@ prune src/qplotter.egg-info
 
 global-exclude .DS_Store
 global-exclude *.py[cod]
+global-exclude *.py[cod].*
 global-exclude *.dll
 global-exclude *.dylib
 global-exclude *.pyd

{qplotter-1.6.0b3 → qplotter-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qplotter
-Version: 1.6.0b3
+Version: 1.6.2
 Summary: PyQt-based viewer for completed and running QCoDeS database experiments
 Author-email: Ben Wordsworth <b.wordsworth@lancaster.ac.uk>, Edward Laird <e.a.laird@lancaster.ac.uk>
 License-Expression: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/lairdgrouplancaster/QCoDeS-Plotter.git
 Project-URL: Source, https://github.com/lairdgrouplancaster/QCoDeS-Plotter
 Project-URL: Issues, https://github.com/lairdgrouplancaster/QCoDeS-Plotter/issues
 Keywords: qcodes,pyqt,pyqtgraph,data-visualization,scientific-computing
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: MacOS X
 Classifier: Environment :: Win32 (MS Windows)
 Classifier: Intended Audience :: Science/Research
@@ -24,7 +24,7 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: qplotter-native==1.0.0
+Requires-Dist: qplotter-native==1.0.1
 Requires-Dist: apsw==3.53.4.0
 Requires-Dist: jsonschema>=4.23.0
 Requires-Dist: numpy>=2.3.1
@@ -46,6 +46,11 @@ Dynamic: license-file
 # QCoDeS-Plotter
 
 [![release](https://img.shields.io/github/v/release/lairdgrouplancaster/QCoDeS-Plotter?label=release)](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/releases/latest)
+[![CI](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/lairdgrouplancaster/QCoDeS-Plotter)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11–3.14-blue?logo=python)](#requirements)
+[![PyPI](https://img.shields.io/pypi/v/qplotter)](https://pypi.org/project/qplotter/)
+
 [![pre-release](https://img.shields.io/github/v/release/lairdgrouplancaster/QCoDeS-Plotter?include_prereleases&label=pre-release&sort=semver)](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/releases)
 
 QCoDeS-Plotter, or qPlot, is a PyQt-based data viewer for QCoDeS databases. It
@@ -79,6 +84,11 @@ selected run's plain detail view without copying the database. Main-database,
 WAL, and rollback-journal handles remain read-only; SQLite may update only the
 exact colocated `-shm` file as transient WAL coordination state.
 
+Measurement viewing supports QCoDeS's standard `sqlite_main_db` storage backend.
+Runs using the optional `sqlite_per_dataset_db` backend can appear in the run
+list, but their measurement actions are refused before opening the separate
+raw-data files. Safe multi-file live viewing is not yet implemented.
+
 Normal `qplot`, `python -m qplot`, and `qplot.run()` launches put the complete
 qPlot process tree behind a shutdown boundary before Qt or reader helpers can
 start. The command-line process is the launcher. A public `qplot.run()` call
@@ -116,16 +126,20 @@ fields and an unavailable detail state without starting a selected-detail
 reader or preparing an additional selected-detail snapshot. That claim applies
 only to row selection: fallback metadata and retained preview paths can still
 create private snapshots. Plot and CSV actions also acquire action-owned
-snapshots. Automatic trusted live
-previews and thumbnails are disabled until the Stage 5 scheduler and disk cache
-are implemented. See
+snapshots. Trusted live previews and thumbnails load progressively through a bounded
+scheduler and application cache. See
 [Trusted live QCoDeS reader](docs/trusted-live-reader.md).
 
 ## Packages
 
 The application distribution is `qplotter`; its Python imports and
 console commands remain `qplot`, `qplot-cfg`, and `qplot-generate-db`.
-The separately built `qplotter-native==1.0.0` supplies the protected
+Use **Help → About qPlot** to see the version in use on every platform.
+Source checkouts also show the commit and
+whether there are local changes. CI-built packages retain their build commit
+and, for pull-request builds, the PR number. Packages installed without build
+provenance still show the release number.
+The separately built `qplotter-native==1.0.1` supplies the protected
 SQLite reader through `qplot_native`. The application's exact dependency pin
 installs the compatible native wheel automatically. Both packages pin the same
 APSW/SQLite runtime, preserving trusted live reading and database protections.
@@ -143,8 +157,8 @@ source builds, and release validation.
 ## Install
 
 Install qPlot inside a supported Python virtual environment. This checkout
-prepares the first split PyPI release, application `1.6.0b3` with native `1.0.0`;
-the commands targeting these packages work after publication. Until then, use
+prepares the stable application release `1.6.2`, with native `1.0.1`.
+The installation examples below work after publication; until then, use
 validated local artifacts as described in [Distribution](docs/distribution.md).
 
 ### Prelude
@@ -174,9 +188,9 @@ For ordinary installation after a stable PyPI release is available:
 python -m pip install --only-binary=:all: qplotter
 ```
 
-For the first split beta, explicitly select the prerelease:
+To select version 1.6.2 explicitly after publication:
 ```console
-python -m pip install --only-binary=:all: qplotter==1.6.0b3
+python -m pip install --only-binary=:all: qplotter==1.6.2
 ```
 
 Both commands install the full runtime dependency set as wheels, with no C
@@ -198,7 +212,7 @@ installing the new packages:
 
 ```console
 python -m pip uninstall -y qplot qcodes-plotter qcodes-plotter-native qplotter qplotter-native
-python -m pip install --only-binary=:all: qplotter==1.6.0b3
+python -m pip install --only-binary=:all: qplotter==1.6.2
 python -m pip check
 ```
 

{qplotter-1.6.0b3 → qplotter-1.6.2}/README.md

@@ -1,6 +1,11 @@
 # QCoDeS-Plotter
 
 [![release](https://img.shields.io/github/v/release/lairdgrouplancaster/QCoDeS-Plotter?label=release)](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/releases/latest)
+[![CI](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/lairdgrouplancaster/QCoDeS-Plotter)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11–3.14-blue?logo=python)](#requirements)
+[![PyPI](https://img.shields.io/pypi/v/qplotter)](https://pypi.org/project/qplotter/)
+
 [![pre-release](https://img.shields.io/github/v/release/lairdgrouplancaster/QCoDeS-Plotter?include_prereleases&label=pre-release&sort=semver)](https://github.com/lairdgrouplancaster/QCoDeS-Plotter/releases)
 
 QCoDeS-Plotter, or qPlot, is a PyQt-based data viewer for QCoDeS databases. It
@@ -34,6 +39,11 @@ selected run's plain detail view without copying the database. Main-database,
 WAL, and rollback-journal handles remain read-only; SQLite may update only the
 exact colocated `-shm` file as transient WAL coordination state.
 
+Measurement viewing supports QCoDeS's standard `sqlite_main_db` storage backend.
+Runs using the optional `sqlite_per_dataset_db` backend can appear in the run
+list, but their measurement actions are refused before opening the separate
+raw-data files. Safe multi-file live viewing is not yet implemented.
+
 Normal `qplot`, `python -m qplot`, and `qplot.run()` launches put the complete
 qPlot process tree behind a shutdown boundary before Qt or reader helpers can
 start. The command-line process is the launcher. A public `qplot.run()` call
@@ -71,16 +81,20 @@ fields and an unavailable detail state without starting a selected-detail
 reader or preparing an additional selected-detail snapshot. That claim applies
 only to row selection: fallback metadata and retained preview paths can still
 create private snapshots. Plot and CSV actions also acquire action-owned
-snapshots. Automatic trusted live
-previews and thumbnails are disabled until the Stage 5 scheduler and disk cache
-are implemented. See
+snapshots. Trusted live previews and thumbnails load progressively through a bounded
+scheduler and application cache. See
 [Trusted live QCoDeS reader](docs/trusted-live-reader.md).
 
 ## Packages
 
 The application distribution is `qplotter`; its Python imports and
 console commands remain `qplot`, `qplot-cfg`, and `qplot-generate-db`.
-The separately built `qplotter-native==1.0.0` supplies the protected
+Use **Help → About qPlot** to see the version in use on every platform.
+Source checkouts also show the commit and
+whether there are local changes. CI-built packages retain their build commit
+and, for pull-request builds, the PR number. Packages installed without build
+provenance still show the release number.
+The separately built `qplotter-native==1.0.1` supplies the protected
 SQLite reader through `qplot_native`. The application's exact dependency pin
 installs the compatible native wheel automatically. Both packages pin the same
 APSW/SQLite runtime, preserving trusted live reading and database protections.
@@ -98,8 +112,8 @@ source builds, and release validation.
 ## Install
 
 Install qPlot inside a supported Python virtual environment. This checkout
-prepares the first split PyPI release, application `1.6.0b3` with native `1.0.0`;
-the commands targeting these packages work after publication. Until then, use
+prepares the stable application release `1.6.2`, with native `1.0.1`.
+The installation examples below work after publication; until then, use
 validated local artifacts as described in [Distribution](docs/distribution.md).
 
 ### Prelude
@@ -129,9 +143,9 @@ For ordinary installation after a stable PyPI release is available:
 python -m pip install --only-binary=:all: qplotter
 ```
 
-For the first split beta, explicitly select the prerelease:
+To select version 1.6.2 explicitly after publication:
 ```console
-python -m pip install --only-binary=:all: qplotter==1.6.0b3
+python -m pip install --only-binary=:all: qplotter==1.6.2
 ```
 
 Both commands install the full runtime dependency set as wheels, with no C
@@ -153,7 +167,7 @@ installing the new packages:
 
 ```console
 python -m pip uninstall -y qplot qcodes-plotter qcodes-plotter-native qplotter qplotter-native
-python -m pip install --only-binary=:all: qplotter==1.6.0b3
+python -m pip install --only-binary=:all: qplotter==1.6.2
 python -m pip check
 ```
 

{qplotter-1.6.0b3 → qplotter-1.6.2}/docs/architecture.md

@@ -245,8 +245,16 @@ unavailable detail state: ordinary selection starts no selected-detail worker
 and prepares no additional selected-detail snapshot. A trusted detail failure
 also does not trigger an automatic fallback copy. This is a property of the
 selection action, not the whole fallback session: fallback metadata and retained
-preview paths can still create private snapshots. Only explicit plot and CSV
-actions materialise a DataSet.
+preview paths can still create private snapshots. Fallback plot actions
+(including Auto-plot) and CSV actions can materialise a DataSet.
+
+Trusted Auto-plot owns a deduplicated queue independently of selected-detail
+and refresh requests. It submits one bounded plot-metadata request at a time,
+then uses the same asynchronous plot pipeline as manual plotting. Unavailable
+descriptions are operation-local failures that leave the reader session usable.
+Retries use bounded backoff; later run-metadata changes wake exhausted requests.
+Disabling Auto-plot, committing a database switch, closing the database, and
+shutdown cancel the queue. Source identity checks still guard publication.
 
 Stage 5A's `trusted_work_scheduler.py` owns the exact derived priority key
 `(run tier, work kind, stable run index)` without materialising one task per

{qplotter-1.6.0b3 → qplotter-1.6.2}/docs/demo-data.md

@@ -65,6 +65,13 @@ database and each run, including elapsed times and whether generation completed,
 was cancelled, or failed. These appear alongside QCoDeS's existing
 `Starting experimental run with id:` messages.
 
+Generation requires QCoDeS's `dataset.raw_data_backend` to be `sqlite_main_db`,
+`dataset.export_automatic` to be false, and
+`subscription.default_subscribers` to be empty. Other settings are rejected
+before creating files because they can write outside the selected output.
+qPlot leaves these global settings unchanged and uses an empty private station
+so synthetic measurements do not read parameters from an acquisition station.
+
 Every nonblank CSV row creates one run, named `run_1`, `run_2`, and so on. A 1D
 row sweeps `V_SD`; a 2D row sweeps both `V_SD` and `V_G`. Each measured signal
 is the sum of two sinusoids with independently randomised amplitudes,

{qplotter-1.6.0b3 → qplotter-1.6.2}/docs/distribution.md

@@ -29,11 +29,15 @@ virtual environment with:
 python -m pip install --only-binary=:all: qplotter
 ```
 
-The first prepared application release is the beta `1.6.0b3`, with exact native
-dependency `1.0.0`. Once published, install that prerelease explicitly:
+The current development target is the stable application release `1.6.2`,
+with exact native dependency `1.0.1`. Existing candidate tags do not establish
+that publication succeeded. Preparing a PR does not publish either package.
+
+The prepared stable application release is `1.6.2`, with exact native
+dependency `1.0.1`. Once published, install that release explicitly:
 
 ```console
-python -m pip install --only-binary=:all: qplotter==1.6.0b3
+python -m pip install --only-binary=:all: qplotter==1.6.2
 ```
 
 The earlier `native-and-app/v1.6.0b2` candidate did not pass its complete hosted
@@ -55,7 +59,7 @@ wheel paths from this revision's validated artifacts together. For example,
 on Windows x64 (replace the application version when appropriate):
 
 ```console
-python -m pip install --only-binary=:all: dist/qplotter_native-1.0.0-cp311-abi3-win_amd64.whl dist/qplotter-1.6.0b3-py3-none-any.whl
+python -m pip install --only-binary=:all: dist/qplotter_native-1.0.1-cp311-abi3-win_amd64.whl dist/qplotter-1.6.2-py3-none-any.whl
 ```
 
 Use your platform's native filename on macOS/Linux. Never mix artifacts from
@@ -87,7 +91,7 @@ application names before installing the replacement:
 
 ```console
 python -m pip uninstall -y qplot qcodes-plotter qcodes-plotter-native qplotter qplotter-native
-python -m pip install --only-binary=:all: qplotter==1.6.0b3
+python -m pip install --only-binary=:all: qplotter==1.6.2
 python -m pip check
 python -c "from importlib.metadata import packages_distributions; p = packages_distributions(); assert set(p['qplot']) == {'qplotter'}; assert set(p['qplot_native']) == {'qplotter-native'}"
 ```
@@ -217,7 +221,7 @@ wheels must build the extension from source.
 
 The native wheel contains the `cp311-abi3` extension
 `qplot_native._trusted_vfs_native` and is platform-specific. The application
-wheel is `py3-none-any`. The application requires exactly native version 1.0.0;
+wheel is `py3-none-any`. The application requires exactly native version 1.0.1;
 both distributions pin APSW 3.53.4.0. Keep these dependencies, the validator's
 pins, and the Python/native SQLite 3.53.4 and source-ID checks coordinated.
 The reader also rejects an incompatible native distribution version, SQLite
@@ -395,8 +399,8 @@ application version from `pyproject.toml`:
 
 | Tag | Native handling | PyPI uploads |
 | --- | --- | --- |
-| `native-and-app/v1.6.0b3` | Build/validate native `1.0.0` at this revision | Native wheels first, then application wheel/sdist |
-| `v1.6.0b4` (example later version) | Fetch/validate the application's exact published native pin | Application wheel/sdist only |
+| `native-and-app/v1.6.2` | Build/validate native `1.0.1` at this revision, if unpublished | Native wheels first, then application wheel/sdist |
+| `v1.6.2` | Fetch/validate the application's exact published native pin | Application wheel/sdist only |
 
 The workflow calls the entire CI workflow at the tagged revision. Failure of
 any build, static check, source-distribution suite, database-protection suite,
@@ -428,9 +432,9 @@ After application publication and byte verification, `public-installations`
 runs on all four platforms and every advertised CPython version (3.11–3.14).
 Each entry creates two fresh environments outside the original checkout.
 The ordinary path runs `python -m pip install --only-binary=:all:
-qplotter==1.6.0b3` against the public PyPI index with all runtime dependencies.
+qplotter==1.6.2` against the public PyPI index with all runtime dependencies.
 The editable path fetches the exact tested commit into a fresh checkout and
-installs `.[dev]` with `qplotter-native==1.0.0` resolved from public PyPI.
+installs `.[dev]` with `qplotter-native==1.0.1` resolved from public PyPI.
 Neither path installs a local release wheel; the validated artifacts are only
 comparison receipts for the pip report and installed-file hashes. All runtime
 and development dependencies must resolve to public wheels. Both paths disable
@@ -440,7 +444,10 @@ protections. Editable acceptance additionally observes a Python edit without
 reinstalling and checks that the native binary's bytes, identity and timestamp
 remain unchanged. Windows uses the standard-user wrapper for both paths.
 Publication is irreversible; failures in these post-publication checks must
-be reported and fixed in a new release, rather than described as acceptance.
+be reported. Changes to published package contents require a new release.
+A defect confined to the validation tools can instead be corrected and the
+existing release rechecked as described below; the failed original run remains
+part of the release record.
 
 ### One-time account configuration
 
@@ -484,10 +491,14 @@ and [pending-publisher instructions](https://docs.pypi.org/trusted-publishers/cr
    release version before tagging; never move a published tag. If migrating
    from token publishing, revoke/remove the old upload tokens/secrets.
 
-### First release commands
+### Application 1.6.2 release commands
+
+Version 1.6.2 contains Python-only changes and retains the published native
+1.0.1 dependency. Use the application-only tag below; published native files
+remain unchanged.
 
 Complete the account setup and merge the reviewed packaging/release changes
-to `main`. With application `1.6.0b3` and native `1.0.0`, use the configured
+to `main`. With application `1.6.2` and native `1.0.1`, use the configured
 Git remote/credentials:
 
 ```console
@@ -495,22 +506,22 @@ git fetch origin
 git switch main
 git pull --ff-only origin main
 python scripts/validate_distribution.py --check-clean
-git tag -a native-and-app/v1.6.0b3 -m "qPlot 1.6.0b3 with native reader 1.0.0"
-git push origin refs/tags/native-and-app/v1.6.0b3
+git tag -a v1.6.2 -m "qPlot 1.6.2"
+git push origin refs/tags/v1.6.2
 ```
 
 Use the activated project venv for Python; on macOS set
 `MPLCONFIGDIR=/private/tmp/qplot-matplotlib-cache` for Python commands that may
 import Matplotlib. The tag push is the publication trigger. Review its hosted
-CI results, then approve the `pypi-native` environment. Confirm native
-verification succeeds before approving `pypi-application`. The final PyPI
+CI results and confirm verification of the published native dependency
+succeeds before approving `pypi-application`. No native publication is needed. The final PyPI
 verification and all `public-installations` jobs must succeed before announcing the release. No GitHub Release
 object is needed to trigger publication; use the connected GitHub app for any
 subsequent release/PR operations if supported, never `gh`.
 
 ### Later Python-only releases
 
-Update the application version (for example to `1.6.0b4`) and changelog, keep
+Update the application version (for example to `1.6.3`) and changelog, keep
 the exact native/APSW pins when still compatible, and merge the changes. Do
 not change native sources/ABI under an existing native version. Then:
 
@@ -519,8 +530,8 @@ git fetch origin
 git switch main
 git pull --ff-only origin main
 python scripts/validate_distribution.py --check-clean
-git tag -a v1.6.0b4 -m "qPlot 1.6.0b4"
-git push origin refs/tags/v1.6.0b4
+git tag -a v1.6.3 -m "qPlot 1.6.3"
+git push origin refs/tags/v1.6.3
 ```
 
 The native release must already contain all four non-yanked compatible wheels.
@@ -537,6 +548,35 @@ the application remains blocked. Once the complete native release is verified,
 an application-only tag for the still-unpublished application version can also
 recover a failed paired release after a new validation run.
 
+### Recheck an existing published release
+
+If post-publication acceptance fails because of a validation-tool defect,
+fix and review the tools, then merge them to `main`. Do not move the release
+tag or rerun a successful publication job. In GitHub Actions, select
+**Revalidate published qPlot release**, then **Run workflow**, using branch
+`main`. Supply the original release tag and publication workflow run ID.
+For the 1.6.0 resource-inventory correction these are `v1.6.0` and
+`38429734516`.
+
+This manual workflow uses the corrected tools from `main`, but checks out
+the original release source separately. It checks the native package version
+pinned by that original source while retaining the tools' supported APSW/SQLite
+ABI checks. It downloads the `qplot-release` artifact from the original
+publication run, verifies its tag, commit, run ID,
+and hashes, and checks the published PyPI bytes against those receipts. The
+artifact must still be available; a missing/expired receipt is a failed gate,
+not permission to substitute a new build. The receipts are comparison inputs;
+ordinary and editable dependencies are still installed from public PyPI.
+All four platforms and CPython 3.11-3.14 run both installation paths, including
+GUI startup and the trusted live reader/database-protection smokes. Windows
+runs unprivileged. The workflow has only read permissions and no publishing
+jobs or deployment approvals.
+
+Wait for all 16 matrix jobs to pass before reporting corrected acceptance.
+Link both the original publication run and the new validation run in the
+release notes. If any failure requires an application or native package change,
+use a new package version and the normal release workflow.
+
 ### Local and hosted results
 
 Local tests and actionlint validate release configuration and failure gates.

{qplotter-1.6.0b3 → qplotter-1.6.2}/docs/trusted-live-reader.md

@@ -265,8 +265,19 @@ proof handles, actual SQLite handles, source pathnames, rollback-journal absence
 and active SHM bindings. Only after that succeeds may page reads reuse pathname
 proofs until operation cleanup. Every page read still validates the retained and
 actual handle identities and their physically read-only permissions, before and
-after delegation. Other callbacks, including SHM mapping/locking, retain their
-full existing checks. Newly opened or promoted WAL handles are fully validated.
+after delegation. SHM mapping and newly opened or promoted WAL handles retain
+their full checks. SHM locks and memory barriers use the binding already proved
+by mapping and operation-boundary validation, without filesystem calls inside
+SQLite's WAL critical sections. Unlocks are forwarded even after a latched
+validation error, allowing SQLite to release its coordination locks on cleanup.
+
+SQLite reads the two WAL-index header copies around `xShmBarrier`. Filesystem
+checks in that callback widen the race with a commit and can force even a
+read-only connection to acquire `WAL_WRITE_LOCK` to retry the header. Checks
+after acquisition or before release then prolong that lock, causing a QCoDeS
+deferred read-to-write upgrade to fail with `SQLITE_BUSY`. The native callbacks
+retain the platform memory fence and real SHM locking, including legitimate
+WAL-index recovery; they neither suppress locks nor bypass them.
 
 Cleanup disables pathname reuse and performs full native validation before any
 materialised result is published, including error, deadline and cancellation
@@ -279,6 +290,11 @@ transaction. Reads outside the explicit finite scope retain per-read path checks
 Native audit counters include `read_path_reused`, `read_validation_ns` and
 `read_io_ns`. The timings separate page-read validation from the delegated OS VFS
 read, not total SQL or IPC time, and never govern safety checks or deadlines.
+`shm_write_lock_attempts`, `shm_write_lock_acquired`, `shm_write_lock_ns` and
+`shm_write_lock_max_ns` expose transient WAL write-lock contention. The durations
+run from successful acquisition return through successful release return; these
+diagnostics do not control locking. A read-only connection can legitimately
+acquire this lock to coordinate the writable WAL index.
 `scripts/profile_trusted_reads.py DATABASE RUN_ID` profiles finite 65,536-row
 intervals through the pinned reader and checks protected-file sizes/timestamps.
 It does not clear OS caches or modify the selected database. Use the actual plot