Use the _PGXNTOOL_/_ prefix for internal test-gate variables and targets

.claude/CLAUDE.md

@@ -25,6 +25,25 @@ Addition specific to this paired repo, on top of the general convention in
 `../../ai/CLAUDE.md`: if you pushed to both pgxntool and pgxntool-test,
 start a background task for each — do not monitor them sequentially.
 
+## Naming: `PGXNTOOL_` Is API, `_PGXNTOOL_` Is Internal
+
+- `PGXNTOOL_*` variables are user-facing override points: document them in
+  README.asc and treat any change as an API change.
+- `_PGXNTOOL_*` variables (and `_pgxntool_*` functions) are internal-only,
+  including seams that exist so pgxntool-test can stub a script. Internal
+  make targets likewise start with `_` (e.g. `_check-stale-expected`), which
+  also keeps them out of `make list`.
+- Internal variables that predate the convention (`TEST_DEPS`,
+  `TEST_SQL_FILES`, `TEST_BUILD_*`, `REGRESS_DBNAME`, `MAJORVER`, `GE91`,
+  ..., plus `PGXNTOOL_DIR`, which keeps its bare prefix) stay as they are,
+  since consumers may reference them. Don't rename them; give every new
+  internal variable the `_PGXNTOOL_` prefix.
+
+pgxntool-test's `test/standard/make-variables.bats` checks every variable
+base.mk defines against the classified list in its
+`test/lib/pgxntool-variables.txt`, so adding a variable means classifying
+it there.
+
 ## HISTORY.asc: Sorted Issue Numbers
 
 The "Issues fixed in this release:" line in HISTORY.asc must list issue

HISTORY.asc

@@ -67,7 +67,8 @@ same `_PGXNTOOL_` consistency): `PGXNTOOL_BASE_MK_INCLUDED` ->
 `_CHECK_STALE_EXPECTED_SCRIPT` -> `_PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT`.
 None of these are documented anywhere as override points, but if you happened
 to reference one directly (unsupported, but possible), update to the new
-name.
+name. The internal `check-stale-expected` target is likewise renamed to
+`_check-stale-expected`; `make test` runs it as before.
 
 == Add `make results-build`
 Refreshes `test/build/expected/*.out` from the last `test-build` run's

README.asc

@@ -206,7 +206,7 @@ Without `test/install`, each test file typically needs to run `CREATE EXTENSION`
 
 **Key detail:** Install files and regular tests run in a single `pg_regress` invocation. This means the database is NOT dropped between install and test phases — state created by install files persists into the main test suite.
 
-WARNING: **`+test/install/*.out+` is never actually compared against anything.** Unlike every other test type pgxntool supports, the `test/install` directory's actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The *only* thing that still fails the build is a hard SQL error, and only if the file sets `ON_ERROR_STOP` (directly, or via `\i test/pgxntool/psql.sql`) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (`check-test-install-error-stop`, see `PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK` to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in `test/sql` instead (or use pgTap assertions from within the install file itself).
+WARNING: **`+test/install/*.out+` is never actually compared against anything.** Unlike every other test type pgxntool supports, the `test/install` directory's actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The *only* thing that still fails the build is a hard SQL error, and only if the file sets `ON_ERROR_STOP` (directly, or via `\i test/pgxntool/psql.sql`) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (`_check-test-install-error-stop`, see `PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK` to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in `test/sql` instead (or use pgTap assertions from within the install file itself).
 
 ==== Update & Upgrade (U&U) Testing
 
@@ -822,13 +822,13 @@ Default: `yes`. Enables or disables the <<_verify_results_safeguard,verify-resul
 
 === PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *
 
-Default: `yes`. Enables or disables the check-stale-expected safeguard, which fails `make test` if `test/expected/` (or `test/build/expected/`) contains a `.out` file with no corresponding `.sql` file -- catching a stale file left behind after a test was renamed or removed. Set to `no` to make the check a complete no-op (it's dropped from `TEST_DEPS` entirely).
+Default: `yes`. Enables or disables the `_check-stale-expected` safeguard, which fails `make test` if `test/expected/` (or `test/build/expected/`) contains a `.out` file with no corresponding `.sql` file -- catching a stale file left behind after a test was renamed or removed. Set to `no` to make the check a complete no-op (it's dropped from `TEST_DEPS` entirely).
 
 This is also the supported pattern for disabling one specific optional pgxntool feature: a documented `PGXNTOOL_ENABLE_*` variable, gating both the target's registration into `TEST_DEPS`/etc. and (where applicable) the target's own definition. Cleanly replacing or overriding an arbitrary pgxntool-generated recipe with your own entirely is a separate, larger, and not-yet-decided design question -- see https://github.com/Postgres-Extensions/pgxntool/issues/30[issue #30] (two proposed approaches) -- and is *not* what this mechanism solves.
 
 === PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *
 
-Default: `yes`. Sub-check of check-stale-expected, independent of `PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED`: fails (with a distinct error message and exit code from the orphaned-`.out` check) if `test/expected/` (or `test/build/expected/`) contains any file that isn't `*.out`. Set to `no` to disable just this sub-check while leaving the orphaned-`.out` check active.
+Default: `yes`. Sub-check of `_check-stale-expected`, independent of `PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED`: fails (with a distinct error message and exit code from the orphaned-`.out` check) if `test/expected/` (or `test/build/expected/`) contains any file that isn't `*.out`. Set to `no` to disable just this sub-check while leaving the orphaned-`.out` check active.
 
 === PGXNTOOL_NO_PGXS_INCLUDE
 

README.html

@@ -926,7 +926,7 @@ <h3 id="_testinstall"><a class="anchor" href="#_testinstall"></a><a class="link"
 <div class="title">Warning</div>
 </td>
 <td class="content">
-<strong><code>test/install/*.out</code> is never actually compared against anything.</strong> Unlike every other test type pgxntool supports, the <code>test/install</code> directory&#8217;s actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The <strong>only</strong> thing that still fails the build is a hard SQL error, and only if the file sets <code>ON_ERROR_STOP</code> (directly, or via <code>\i test/pgxntool/psql.sql</code>) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (<code>check-test-install-error-stop</code>, see <code>PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK</code> to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in <code>test/sql</code> instead (or use pgTap assertions from within the install file itself).
+<strong><code>test/install/*.out</code> is never actually compared against anything.</strong> Unlike every other test type pgxntool supports, the <code>test/install</code> directory&#8217;s actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The <strong>only</strong> thing that still fails the build is a hard SQL error, and only if the file sets <code>ON_ERROR_STOP</code> (directly, or via <code>\i test/pgxntool/psql.sql</code>) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (<code>_check-test-install-error-stop</code>, see <code>PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK</code> to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in <code>test/sql</code> instead (or use pgTap assertions from within the install file itself).
 </td>
 </tr>
 </table>
@@ -2172,7 +2172,7 @@ <h3 id="_pgxntool_enable_verify_results"><a class="anchor" href="#_pgxntool_enab
 <div class="sect2">
 <h3 id="_pgxntool_enable_check_stale_expected"><a class="anchor" href="#_pgxntool_enable_check_stale_expected"></a><a class="link" href="#_pgxntool_enable_check_stale_expected">8.16. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *</a></h3>
 <div class="paragraph">
-<p>Default: <code>yes</code>. Enables or disables the check-stale-expected safeguard, which fails <code>make test</code> if <code>test/expected/</code> (or <code>test/build/expected/</code>) contains a <code>.out</code> file with no corresponding <code>.sql</code> file&#8201;&#8212;&#8201;catching a stale file left behind after a test was renamed or removed. Set to <code>no</code> to make the check a complete no-op (it&#8217;s dropped from <code>TEST_DEPS</code> entirely).</p>
+<p>Default: <code>yes</code>. Enables or disables the <code>_check-stale-expected</code> safeguard, which fails <code>make test</code> if <code>test/expected/</code> (or <code>test/build/expected/</code>) contains a <code>.out</code> file with no corresponding <code>.sql</code> file&#8201;&#8212;&#8201;catching a stale file left behind after a test was renamed or removed. Set to <code>no</code> to make the check a complete no-op (it&#8217;s dropped from <code>TEST_DEPS</code> entirely).</p>
 </div>
 <div class="paragraph">
 <p>This is also the supported pattern for disabling one specific optional pgxntool feature: a documented <code>PGXNTOOL_ENABLE_*</code> variable, gating both the target&#8217;s registration into <code>TEST_DEPS</code>/etc. and (where applicable) the target&#8217;s own definition. Cleanly replacing or overriding an arbitrary pgxntool-generated recipe with your own entirely is a separate, larger, and not-yet-decided design question&#8201;&#8212;&#8201;see <a href="https://github.com/Postgres-Extensions/pgxntool/issues/30">issue #30</a> (two proposed approaches)&#8201;&#8212;&#8201;and is <strong>not</strong> what this mechanism solves.</p>
@@ -2181,7 +2181,7 @@ <h3 id="_pgxntool_enable_check_stale_expected"><a class="anchor" href="#_pgxntoo
 <div class="sect2">
 <h3 id="_pgxntool_check_expected_file_types"><a class="anchor" href="#_pgxntool_check_expected_file_types"></a><a class="link" href="#_pgxntool_check_expected_file_types">8.17. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *</a></h3>
 <div class="paragraph">
-<p>Default: <code>yes</code>. Sub-check of check-stale-expected, independent of <code>PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED</code>: fails (with a distinct error message and exit code from the orphaned-<code>.out</code> check) if <code>test/expected/</code> (or <code>test/build/expected/</code>) contains any file that isn&#8217;t <code>*.out</code>. Set to <code>no</code> to disable just this sub-check while leaving the orphaned-<code>.out</code> check active.</p>
+<p>Default: <code>yes</code>. Sub-check of <code>_check-stale-expected</code>, independent of <code>PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED</code>: fails (with a distinct error message and exit code from the orphaned-<code>.out</code> check) if <code>test/expected/</code> (or <code>test/build/expected/</code>) contains any file that isn&#8217;t <code>*.out</code>. Set to <code>no</code> to disable just this sub-check while leaving the orphaned-<code>.out</code> check active.</p>
 </div>
 </div>
 <div class="sect2">
@@ -2217,7 +2217,7 @@ <h2 id="_copyright"><a class="anchor" href="#_copyright"></a><a class="link" hre
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-10-07 16:52:43 -0500
+Last updated 2026-10-07 17:56:47 -0500
 </div>
 </div>
 </body>