Verification ledger

July 28, 2026 · View on GitHub

Evidence policy

This file records commands that were actually executed, not intended coverage.

Passed: the named command ran in the named environment and exited successfully.
Failed, then passed: an observed failure was diagnosed, changed, and a fresh rerun passed.
Not run: source or configuration exists, but no execution was observed.
Not proven: partial evidence does not prove the full claim.

A workflow, preset, test binary, benchmark harness, or Docker Compose file existing in the repository is not by itself a pass. Unless stated otherwise, the final evidence below was collected on 2026-07-26.

Acceptance summary

The local Windows and Linux acceptance gates passed, including real PGMQ integration, crash recovery, package consumption, sanitizers, static analysis, documentation generation, examples, real-database CLI operations, and one benchmark smoke run. PostgreSQL 14 through 18 were exercised against PGMQ 1.12.0. The public repository and main branch were then created and pushed.

GitHub Actions run 30199851801 was the first hosted execution. All five jobs ran: Linux ASan/UBSan and clang-tidy passed; the Linux documentation gate, Windows shell syntax, and macOS standard-library portability failed. The failures and focused local fix validation are recorded below.

Follow-up run 30200789701 then passed all five jobs on source commit 58edaa86976ba510a38206f290f571705e813645. This includes the first real hosted macOS pass and a Linux run of the real PGMQ fixture, package consumer, integration, crash, and multiprocess tests.

The following remain deliberately separate:

hosted macOS build/unit and the complete five-job workflow are Passed on source commit 58edaa86976ba510a38206f290f571705e813645;
this documentation-only ledger successor must pass the same workflow before the v1.0.0 tag and source Release are created;
at ledger-authoring time the v1.0.0 tag and hosted Release were Not run;
the benchmark is a small functional measurement, not a stable performance claim.

Reproducible database fixture

The normal integration fixture is defined by docker-compose.yml and binds only to loopback. It uses project-owned, disposable storage and is never redirected to a private, shared, or production database.

Property	Value
Image	`ghcr.io/pgmq/pg18-pgmq@sha256:9410102ea5fc16428be5b7203fdfef372827039f57ae05874e8c2e6f45e15336`
PostgreSQL	18.4, `server_version_num = 180004`
PGMQ	1.12.0
pg_partman	5.1.0
Initialization	`tests/docker/001-create-pgmq.sql`
Storage	tmpfs, project-owned and disposable
Health check	verifies `pg_extension.extversion = '1.12.0'`

PGMQ_CPP_REGISTER_DOCKER_TESTS defaults to OFF for a direct CMake configuration. The final Windows all-target configurations enabled it explicitly. CTest fixtures started and stopped each database around the selected integration tests.

Test inventory

CTest name	Labels	Evidence target
`pgmq_unit`	`unit`	validation, versions, SQL NULL/result behavior, errors, retry math and boundaries, dispositions, lifecycle, metrics
`pgmq_installed_consumer`	`package`	install/export, independent `find_package`, linking and running both exported targets
`pgmq_docker_up`	`integration;fixture`	pinned real PostgreSQL/PGMQ startup
`pgmq_integration_sdk`	`integration;sdk`	capabilities, queue lifecycle, typed/raw/batch operations, timestamps, visibility, metrics, polling, caller transactions, reconnect, FIFO, topics
`pgmq_integration_worker`	`integration;worker`	concurrency, retry/DLQ/replay, transactional commit/rollback, lease renewal/loss, reconnect, polling fallback, shutdown
`pgmq_integration_crash`	`integration;crash`	deterministic process termination at seven boundaries
`pgmq_integration_multiprocess`	`integration;worker;multiprocess`	two independent workers competing for one task while renewal prevents overlap
`pgmq_docker_down`	`integration;fixture`	fixture cleanup

The crash executable pair is pgmq_crash_orchestrator and pgmq_crash_worker. A flushed marker establishes each kill boundary before the orchestrator uses SIGKILL or TerminateProcess.

The seven scenarios are:

before_claim
after_claim_before_handler
handler_running
regular_side_effect_after_before_ack
transaction_before_commit
regular_after_ack
transaction_after_commit

Final build and test matrix

Windows

Each row below used a fresh build directory, Visual Studio 17 2022, MSVC 19.41, x64-windows, /W4 /WX, and all optional project targets: tests, Docker integration, CLI, examples, and benchmarks. Each installed consumer printed:

consumer linked pgmq::client and pgmq::worker 1.0.0

Build directory	Configuration	Libraries	Fixture port	Build	CTest
`build/goal2-win-debug-static-v1final`	Debug	static	55442	Passed, all targets	Passed, 8/8
`build/goal2-win-release-static-v1final`	Release	static	55443	Passed, all targets	Passed, 8/8
`build/goal2-win-debug-shared-v1final`	Debug	shared	55444	Passed, all targets	Passed, 8/8
`build/goal2-win-release-shared-v1final`	Release	shared	55445	Passed, all targets	Passed, 8/8

Every 8-test run included the unit test, installed consumer, fixture setup and cleanup, SDK integration, worker integration, crash orchestration, and multiprocess competition. In each run the unit suite passed 11/11, the SDK suite passed 7/7, the worker suite passed 16/16, and the process summaries were:

CRASH_SUMMARY tasks=7 completed=7 duplicates=1
COMPETITION_SUMMARY workers=2 calls=1 overlap=0 completed=1 renewals=3

The one duplicate is the expected regular-mode at-least-once window after an external side effect and before acknowledgement. It is not evidence of exactly-once external effects.

The first final all-target MSVC compile exposed a windows.h max macro collision in the new integral-index bounds check. The implementation changed the call to the macro-safe (std::numeric_limits<std::size_t>::max)() form, then all four rows above were rebuilt with --clean-first and rerun successfully. No pre-fix result is counted as acceptance evidence.

A representative direct configuration was:

cmake -S . -B build/goal2-win-release-shared-v1final `
  -G "Visual Studio 17 2022" -A x64 `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
  -DVCPKG_TARGET_TRIPLET=x64-windows `
  -DBUILD_SHARED_LIBS=ON `
  -DBUILD_TESTING=ON `
  -DPGMQ_CPP_REGISTER_DOCKER_TESTS=ON `
  -DPGMQ_CPP_TEST_PORT=55445 `
  -DPGMQ_CPP_BUILD_CLI=ON `
  -DPGMQ_CPP_BUILD_EXAMPLES=ON `
  -DPGMQ_CPP_BUILD_BENCHMARKS=ON `
  -DPGMQ_CPP_WARNINGS_AS_ERRORS=ON
cmake --build build/goal2-win-release-shared-v1final `
  --config Release --parallel --clean-first
ctest --test-dir build/goal2-win-release-shared-v1final `
  -C Release --output-on-failure --no-tests=error

The other three rows changed only the build directory, configuration, BUILD_SHARED_LIBS, and fixture port shown in the table.

For shared Windows consumers, the project DLLs under the install prefix bin and the selected vcpkg triplet's runtime DLLs must be on the runtime search path. The installed-consumer test performs this deployment for its isolated run. cmake --install does not claim to bundle libpq, OpenSSL, or other third-party runtime DLLs.

Linux

The Linux runs used Ubuntu 24.04.4, CMake 3.28.3, Ninja 1.11.1, warnings as errors, and fresh build directories. The observed local validation image ID was sha256:f7125a0e7c00d85b8c7f3487f6a9e7a9176156419306bbdab564ca3d4d871195.

Build directory	Compiler/configuration	Libraries	Ninja	CTest
`build/goal2-linux-gcc-v1final`	GCC 13.3, Debug	static	Passed, 28/28	Passed, 2/2
`build/goal2-linux-clang-v1final`	Clang 18.1.3, Release	static	Passed, 28/28	Passed, 2/2
`build/goal2-linux-shared-v1final`	Clang 18.1.3, Release	shared	Passed, 30/30	Passed, 2/2

The two CTest cases were the unit suite and installed consumer. The shared build's 30 Ninja steps comprise 28 compile/link steps and two SONAME symlink steps. Its package test installed to an independent prefix, configured an external consumer with find_package, and proved that RUNPATH and ldd resolved the installed .so files. The consumer also ran successfully from /tmp, outside both the source and install trees.

The exact shared-library configuration was:

cmake -S . -B build/goal2-linux-shared-v1final -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_COMPILER=clang++-18 \
  -DBUILD_SHARED_LIBS=ON \
  -DPGMQ_CPP_WARNINGS_AS_ERRORS=ON \
  -DBUILD_TESTING=ON \
  -DPGMQ_CPP_REGISTER_DOCKER_TESTS=OFF
cmake --build build/goal2-linux-shared-v1final --parallel 2
ctest --test-dir build/goal2-linux-shared-v1final \
  -LE integration --output-on-failure -V

The static configurations used the same target set with BUILD_SHARED_LIBS=OFF and the compiler/configuration shown in the table.

Sanitizers and static analysis

Check	Environment	Status	Evidence
GCC ASan + UBSan	GCC 13.3, Debug, `build/goal2-linux-sanitize-gcc-v1final`	Passed	Ninja 18/18; unit CTest 1/1 (11/11 internal cases)
Clang ASan + UBSan	Clang 18.1.3, Debug, `build/goal2-linux-sanitize-clang-v1final`	Failed, then passed	Initial link failed because the image lacked `libclang_rt`; after installing `libclang-rt-18-dev`, Ninja 18/18 and unit CTest 1/1 (11/11 internal cases) passed
clang-tidy	Clang/clang-tidy 18.1.3, Debug, `build/goal2-linux-tidy-v1final`	Passed	8/8 production translation-unit steps, `-warnings-as-errors=*`, zero unsuppressed diagnostics

The sanitizer configurations enabled PGMQ_CPP_ENABLE_SANITIZERS=ON, warnings as errors, and unit tests; Docker integration, CLI, examples, and benchmarks were disabled to keep the sanitizer target focused.

The strict tidy configuration was:

cmake -S . -B build/goal2-linux-tidy-v1final -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_COMPILER=clang++-18 \
  -DBUILD_TESTING=OFF \
  -DPGMQ_CPP_BUILD_CLI=OFF \
  -DPGMQ_CPP_BUILD_EXAMPLES=OFF \
  -DPGMQ_CPP_BUILD_BENCHMARKS=OFF \
  "-DCMAKE_CXX_CLANG_TIDY=clang-tidy-18;-checks=-*,bugprone-*,performance-*,portability-*;-warnings-as-errors=*;-header-filter=^/src/(include|src)/"
cmake --build build/goal2-linux-tidy-v1final --parallel 2

Real PostgreSQL/PGMQ evidence

PostgreSQL 18 complete suite

The pinned PostgreSQL 18.4/PGMQ 1.12.0 fixture passed:

Evidence	Result
SDK integration	7/7
Worker integration	16/16
Crash tasks	7 total, 7 completed, 1 expected duplicate
Multiprocess competition	2 workers, 1 handler call, 0 overlap, 1 completion, 3 renewals

The worker suite covers bounded concurrency and backpressure, regular and transactional retries, atomic DLQ moves and replay, database-clock lease mapping, renewal and lease loss, notification fallback, reconnect, terminal action failures, and clean/timed-out shutdown.

PostgreSQL 14–18 matrix

Each image was started on a separate loopback port. The SDK suite passed 7/7 and the worker suite passed 16/16 on every row. Both new transactional retry-boundary cases passed on all five PostgreSQL majors: the exact maximum was accepted, and a manually assembled maximum-plus-one result invoked its handler once before dead-lettering.

PostgreSQL	`server_version_num`	Image tag	Observed digest	Port	Result
14.23	140023	`ghcr.io/pgmq/pg14-pgmq:v1.12.0`	`sha256:e9dc9be2a444c4e33ee4bedfe5ae9964f9988be8042e3c3bbf7f9894939751a1`	55614	Passed
15.18	150018	`ghcr.io/pgmq/pg15-pgmq:v1.12.0`	`sha256:1f979c68e26c85237b240561c83ab64b3c1dff0946f59eed8026d15d00bcd707`	55615	Passed
16.14	160014	`ghcr.io/pgmq/pg16-pgmq:v1.12.0`	`sha256:9f85a693f97ef60036c02b2ae560471a2e886c4b00117132c838f297631b7f0a`	55616	Passed
17.10	170010	`ghcr.io/pgmq/pg17-pgmq:v1.12.0`	`sha256:a9769edc2a7270afae8d37510fc12ef1852f54eaeb8f97f0cd93e88f654b8e7e`	55617	Passed
18.4	180004	`ghcr.io/pgmq/pg18-pgmq:v1.12.0`	`sha256:9410102ea5fc16428be5b7203fdfef372827039f57ae05874e8c2e6f45e15336`	55618	Passed

All five images reported PGMQ 1.12.0 and pg_partman 5.1.0. The first attempted Scarf image tags failed with repository ... not found: name unknown; the matrix was rerun with the public GHCR images above. Fixture teardown left zero final-matrix containers.

Packaging and dependency evidence

The manifest pins vcpkg baseline 40f3c709db80acf154ac4b17a1f83c564ebd022e. A fresh, separate vcpkg checkout using tool release 2026-07-13 completed the manifest installation successfully. The public project dependencies resolved as:

libpq 18.4;
nlohmann-json 3.12.0#2.

The first Strawberry Perl download attempt ended with curl error 56. A later retry completed and the final manifest log reported:

All requested installations completed successfully

An older Visual Studio-bundled vcpkg checkout was also tried and failed because all of its retired MSYS2 pkgconf 2.2.0 package URLs returned HTTP 404. That toolchain was not used as successful evidence. Repository-local _tools or build-cache directories are not project dependencies.

The installed-consumer test passed in all four Windows configurations and all three Linux configurations. This proves both exported targets, pgmq::client and pgmq::worker, can be found, linked, and executed from an independent consumer.

CLI, examples, and benchmark

The final GCC build's build/goal2-linux-gcc-v1final/tools/pgmq-cppctl/pgmq-cppctl printed version 1.0.0 and ran against PostgreSQL 18.4 / PGMQ 1.12.0 on loopback port 55448. The Compose project was pgmq-cpp-cli-v1final.

The first final-source CLI smoke wrapper exited 2 because its Bash grep expression was quoted incorrectly; the fixture was cleaned and the CLI program had not executed. The corrected command then passed. This was a harness-command failure, not a hidden application pass.

The subsequent complete CLI chain passed:

Operation	Observed result
capabilities	PostgreSQL 18.4 and PGMQ 1.12.0 reported
list and metrics	completed against the isolated fixture
targeted dry run, `--id 1 --dry-run`	selected 1, replayed 0; source `read_ct` changed from 0 to 1
targeted replay, `--id 1`	selected 1, replayed 1; destination length became 1
setup for batch replay	`send_batch` created DLQ ids 2 and 3
batch replay, `--batch 2`	selected 2, replayed 2
final state	DLQ length 0; destination length 3

docker compose down --volumes then removed the CLI fixture; zero containers from that Compose project remained.

All three examples ran against real PostgreSQL 18.4/PGMQ 1.12.0:

basic_producer_worker sent and processed concurrent work;
transactional_orders demonstrated caller rollback, handler retry rollback, and final atomic commit;
crash_recovery terminated a worker, observed redelivery, and drained the queue.

The final benchmark smoke command was:

./build/goal2-linux-gcc-v1final/benchmarks/pgmq-cpp-benchmark \
  --dsn 'postgresql://pgmq:pgmq@127.0.0.1:55447/pgmq' \
  --messages 50 \
  --output build/goal2-linux-gcc-v1final/benchmark-v1final.json

The run's ignored workspace artifact, build/goal2-linux-gcc-v1final/benchmark-v1final.json, recorded GCC 13.3 Debug, PostgreSQL 18.4, PGMQ 1.12.0, and 50 messages. It was removed with the other temporary validation outputs after these results were transcribed:

Measurement	Observed value
single send	826.233 messages/s
batch send	13685.009 messages/s
consume, 1 worker	216.067 messages/s
consume, 2 workers	402.547 messages/s
consume, 4 workers	757.895 messages/s
consume, 8 workers	1080.704 messages/s
polling wake-up	404.678 ms
LISTEN/NOTIFY wake-up	4.913 ms
idle approximate CPU	0.209%
idle estimated empty reads	3.997/s

The run proves that the harness executes and records its required fields. Its small message count, Debug build, one machine, and one database make the numbers unsuitable as a stable throughput promise or cross-system comparison.

Documentation gate

Doxygen 1.9.8 generated build/doxygen/html/index.html with zero warnings and zero errors. The final gate uses WARN_AS_ERROR = FAIL_ON_WARNINGS; generated HTML was subsequently removed as a temporary validation output. The Windows host had no doxygen executable on PATH, so the successful gate was run in the Ubuntu 24.04 validation environment and is not described as a native Windows Doxygen pass.

A deliberate broken-link probe produced one diagnostic and exit code 1, proving that the gate fails on a structural documentation error. Before the Doxyfile input and strictness repair, the baseline had two broken Markdown references but exited 0. The zero-warning result is therefore evidence for the configured parser/link gate, not a claim that every public symbol has a full API comment; WARN_IF_UNDOCUMENTED remains disabled.

Reproduction:

doxygen Doxyfile

Acceptance evidence mapping

Requirement	Executable evidence	Status
SDK operations match the supported PGMQ API	SDK integration on PostgreSQL 14–18	Passed
Batch operations and caller transaction commit/rollback	SDK integration	Passed
Multi-thread/process valid-lease ownership	worker and multiprocess integration	Passed; one call and zero overlap
Long-task renewal	worker and multiprocess integration	Passed; competition observed three renewals
Retry, delay, DLQ content, and replay	unit, worker integration, and final CLI replay chain	Passed
Retry duration exactness and bounds	unit boundary tests plus real PostgreSQL worker integration	Passed at `9,007,199,254,740 ms`; negative and above-bound values rejected before SQL
Transactional business work and acknowledgement are atomic	worker integration and transactional example	Passed within one PostgreSQL database
Notification latency path and polling fallback	SDK/worker integration and benchmark	Passed
Listener/database reconnect	SDK and worker integration	Passed
Graceful shutdown and no false acknowledgement	worker integration	Passed
Deterministic process crashes	crash integration	Passed at all seven boundaries
External installed consumer	Windows and Linux static/shared package tests	Passed
Static and shared delivery	four Windows and three Linux configurations	Passed
CLI version, capabilities, list, metrics, and DLQ replay	real PostgreSQL 18.4/PGMQ 1.12.0	Passed
Three runnable examples	real PostgreSQL 18.4/PGMQ 1.12.0	Passed
Reproducible benchmark harness	final Linux smoke artifact	Passed as execution evidence only
Linux ASan/UBSan	GCC and Clang fresh builds	Passed
Strict static analysis	clang-tidy 18	Passed
Generated documentation gate	Doxygen 1.9.8 plus negative probe	Passed
macOS build/unit	GitHub-hosted macOS 15.7.7 ARM64, Apple Clang 17.0.0 / Xcode 16.4	Passed in run `30200789701`; unit and installed consumer 2/2
GitHub-hosted workflow	GitHub Actions run `30200789701`	Passed; all five jobs on commit `58edaa86976ba510a38206f290f571705e813645`
Public repository and `main` push	GitHub	Passed; initial commit `a68abe5a1e52bb15d2faa8a6dadd4f8cae6ecbe6` is public
v1.0.0 tag and source Release	GitHub	Not run at ledger-authoring time; intentionally gated on this ledger successor's hosted pass
Precompiled package upload	GitHub/registries	Not run; intentionally out of scope for v1.0.0

Crash semantics recorded by the test

The final crash suite completed all seven unique tasks. Its one duplicate was the intentional regular-mode window:

claim -> external side effect succeeds -> process dies -> ack is absent

After lease expiry, another attempt repeats the handler. Transactional pre-commit crashes instead rolled back claim, business SQL, and acknowledgement together. Post-commit cases retained both business state and acknowledgement. The project therefore claims at-least-once regular delivery and same-database transactional atomicity, never exactly-once effects in an external system.

Final audit correction

The last code audit found that extreme floating-point retry arithmetic and oversized explicit retry delays could overflow, lose interval precision, or make a worker repeatedly re-enter work without progress. The correction:

makes exponential backoff saturate safely without an out-of-range floating-point-to-integer conversion;
applies one inclusive 0..9,007,199,254,740 ms range to explicit HandlerResult::retry delays, registered retry policies, and regular plus transactional scheduling;
binds both regular and transactional retry SQL as validated bigint milliseconds;
rejects invalid values as invalid_input before visibility SQL;
converts a manually assembled over-limit retry result to one deterministic dead-letter in both modes, with a handler_failed event;
emits handler_failed if transactional runtime scheduling itself fails;
verifies the transactional maximum against real PostgreSQL, including exact interval representation and a far-future visibility timestamp, and verifies that a transactional maximum-plus-one aggregate bypass invokes the handler only once before DLQ.

The bound is derived by keeping PostgreSQL's float8-backed interval calculation at or below 2^53 internal microseconds. It is an exactness guard, not a recommendation to schedule multi-century retries.

Focused current-source reruns after that correction passed:

Check	Result
MSVC 19.41 Debug unit suite	11/11
Clang 18.1 Release warnings-as-errors build and unit suite	Passed; unit 11/11
GCC 13.3 ASan/UBSan warnings-as-errors unit suite	11/11
PostgreSQL 18 worker integration	16/16, including transactional exact-maximum and aggregate maximum-plus-one cases
PostgreSQL 18 fixture cleanup	Passed; zero project containers remained

Installed-consumer dependency-context follow-up

An independent audit found a gap in the test fixture, rather than in the installed package contract. A parent configure without a vcpkg toolchain successfully found libpq and nlohmann/json through standard CMake hints, but the original pgmq_installed_consumer child received only the pgmq-cpp install prefix. The child therefore failed in the installed pgmq-cpp-config.cmake -> find_dependency(PostgreSQL) call with:

Could NOT find PostgreSQL (missing: PostgreSQL_LIBRARY PostgreSQL_INCLUDE_DIR)

The failure was reproduced in the fresh build/audit-consumer-nontoolchain-before directory. Its MSVC 19.41 warnings-as-errors build passed, and the non-integration CTest run passed the unit executable but failed the installed consumer: 1/2 passed.

The fixture now generates a bracket-quoted CMake initial-cache file at parent configure time. It places the consumer install prefix first, then preserves the parent's CMAKE_PREFIX_PATH list and non-empty PostgreSQL_ROOT, PostgreSQL_DIR, and nlohmann_json_DIR hints. The child loads that file with cmake -C; the existing toolchain, vcpkg installed-directory, and triplet arguments remain unchanged. On Windows, each inherited prefix's bin directory and PostgreSQL_ROOT/bin are also portable runtime-DLL candidates. No source-tree dependency path is hard-coded.

The final non-toolchain rerun used a deliberately harmless prefix containing spaces plus the real dependency prefix in one semicolon-separated list:

$dependency_prefix = (Resolve-Path .\vcpkg_installed\x64-windows).Path
$space_prefix = (Resolve-Path '.\build\dependency hint with spaces').Path
cmake -S . -B build/audit-consumer-nontoolchain-final `
  -G "Visual Studio 17 2022" -A x64 `
  "-DCMAKE_PREFIX_PATH=$space_prefix;$dependency_prefix" `
  "-DPostgreSQL_ROOT=$dependency_prefix" `
  -DBUILD_TESTING=ON `
  -DPGMQ_CPP_REGISTER_DOCKER_TESTS=OFF `
  -DPGMQ_CPP_WARNINGS_AS_ERRORS=ON `
  -DPGMQ_CPP_BUILD_CLI=OFF `
  -DPGMQ_CPP_BUILD_EXAMPLES=OFF `
  -DPGMQ_CPP_BUILD_BENCHMARKS=OFF
cmake --build build/audit-consumer-nontoolchain-final `
  --config Release --parallel --clean-first
ctest --test-dir build/audit-consumer-nontoolchain-final `
  -C Release --label-exclude integration `
  --output-on-failure --no-tests=error -V

The generated child cache retained all three prefix entries, including the entry containing spaces. The child rediscovered PostgreSQL 18.4 and nlohmann-json 3.12.0, built, linked, copied its runtime DLLs, and printed:

consumer linked pgmq::client and pgmq::worker 1.0.0

The final result was Passed, 2/2: unit 11/11 internally and installed consumer 1/1.

A separate minimal vcpkg-toolchain regression used vcpkg tool 2026-07-13-bf04c909169fdbb30821c02c6eb01f1cd1295d05 at the manifest's 40f3c709db80acf154ac4b17a1f83c564ebd022e baseline:

$source_dir = (Resolve-Path .).Path
$vcpkg_root = $env:VCPKG_ROOT
$installed_dir = Join-Path $source_dir 'vcpkg_installed'
$build_dir = Join-Path $source_dir 'build/audit-consumer-vcpkg-final'
cmake -S $source_dir -B $build_dir `
  -G "Visual Studio 17 2022" -A x64 `
  "-DCMAKE_TOOLCHAIN_FILE=$vcpkg_root/scripts/buildsystems/vcpkg.cmake" `
  "-DVCPKG_INSTALLED_DIR=$installed_dir" `
  -DVCPKG_TARGET_TRIPLET=x64-windows `
  -DBUILD_TESTING=ON `
  -DPGMQ_CPP_REGISTER_DOCKER_TESTS=OFF `
  -DPGMQ_CPP_WARNINGS_AS_ERRORS=ON `
  -DPGMQ_CPP_BUILD_CLI=OFF `
  -DPGMQ_CPP_BUILD_EXAMPLES=OFF `
  -DPGMQ_CPP_BUILD_BENCHMARKS=OFF
cmake --build $build_dir `
  --config Release --parallel --target pgmq_client pgmq_worker
ctest --test-dir $build_dir `
  -C Release -R '^pgmq_installed_consumer$' `
  --output-on-failure --no-tests=error -V

The manifest install reported the dependencies already installed, the child loaded both the initial cache and the original toolchain arguments, and the consumer configured, linked, and ran successfully: Passed, 1/1.

The older Visual Studio-bundled vcpkg was retried first and again failed on the retired pkgconf 2.2.0 URLs with HTTP 404; it is not counted as regression evidence. The current tool restored the dependency cache from its binary archives. Its downloaded-tool step also required a temporary ASCII drive mapping for this Unicode workspace path; that mapping was removed after validation. All focused audit-consumer-*, temporary dependency-prefix, and temporary vcpkg-checkout directories from this follow-up were removed after the results were transcribed.

No product C++ source changed in this follow-up. The PostgreSQL 14–18, sanitizer, clang-tidy, and core integration matrices were therefore intentionally not rerun; their earlier evidence above remains unchanged.

Initial GitHub-hosted run and portability fix

The first public commit was a68abe5a1e52bb15d2faa8a6dadd4f8cae6ecbe6. GitHub Actions run 30199851801 completed with these observed results:

Job	Environment	Result
clang-tidy	Ubuntu 24.04, clang-tidy 18.1.3	Passed
Linux ASan and UBSan	Ubuntu 24.04, GCC 13.3	Passed; unit suite ran under both sanitizers
Linux build, package, and real PGMQ	Ubuntu 24.04	Failed at Doxygen after configure/build passed; six README hash references and one unindexed `SECURITY.md` reference were unresolved, so package and integration steps were skipped
Windows build and unit tests	`windows-2022`, MSVC 19.44	Failed before build because a Bash continuation backslash was parsed by PowerShell; vcpkg bootstrap and configure had passed
macOS build and unit tests	macOS 15.7.7 ARM64, Apple Clang 17.0.0 from Xcode 16.4, CMake 4.4.0	Failed during product compilation: libc++ required `-fexperimental-library` for the C++20 stop-token surface, and floating-point `std::from_chars` was unavailable

The fix preserves every job and gate. It changes the Windows continuation to PowerShell syntax, makes all Doxygen inputs resolvable, compile-links the full C++20 stop-token surface and conditionally propagates -fexperimental-library, and replaces floating epoch parsing with a strict classic-locale, range-checked path. No warning-as-error, sanitizer, documentation, package, integration, or platform check was disabled.

A fresh non-toolchain MSVC 19.41 Release build using the ignored local dependency prefix (as a standard CMake search prefix, not as a toolchain) was then rerun with:

$repo = Resolve-Path .
$dependencyPrefix = Join-Path $repo "vcpkg_installed\x64-windows"
cmake -S . -B build/ci-fix-preflight -A x64 `
  "-DCMAKE_PREFIX_PATH=$dependencyPrefix" `
  "-DPostgreSQL_ROOT=$dependencyPrefix" `
  -DBUILD_TESTING=ON `
  -DPGMQ_CPP_REGISTER_DOCKER_TESTS=OFF `
  -DPGMQ_CPP_WARNINGS_AS_ERRORS=ON
cmake --build build/ci-fix-preflight --config Release --parallel
ctest --test-dir build/ci-fix-preflight -C Release `
  --label-exclude integration --output-on-failure --no-tests=error

Result: build passed with /W4 /WX; CTest passed 2/2; the unit binary passed 13/13 internal cases; the installed consumer compiled, linked, and ran, including the stop-token/callback/jthread/stop-aware-condition-variable surface. actionlint 1.7.12 also passed. A fresh Ubuntu 24.04 container then ran doxygen Doxyfile: exit 0, zero warning/error diagnostics, and a non-empty 39,356-byte build/doxygen/html/index.html.

First complete GitHub-hosted pass

Source commit 58edaa86976ba510a38206f290f571705e813645 was pushed to main. GitHub Actions run 30200789701 completed with all five jobs successful:

Job	Hosted environment and result
Linux build, package, and real PGMQ	Ubuntu 24.04, GCC 13.3.0, 28/28 build; Doxygen 1.9.8; unit plus installed consumer 2/2; real fixture, SDK, Worker, crash, multiprocess, and cleanup 6/6
Linux ASan and UBSan	Ubuntu 24.04, GCC 13.3.0, 18/18 build; leak detection and strict string checks enabled; UBSan halted on error; unit CTest 1/1
clang-tidy	Ubuntu 24.04, LLVM/clang-tidy 18.1.3; `warnings-as-errors=*`; production-target build 8/8
Windows build and unit tests	Windows Server 2022 image `20260720.249.2`, MSVC 19.44.35228; `/W4 /WX`; native stop-token mode; unit plus installed consumer 2/2
macOS build and unit tests	macOS 15.7.7 ARM64 image `20260715.0234.1`, Xcode 16.4 Apple Clang 17.0.0, CMake 4.4.0, libpq 18.4; verified `-fexperimental-library` mode; unit plus installed consumer 2/2

The Linux integration job also ran its always() cleanup step successfully. The macOS consumer was configured from the installed package, so its successful compile, link, and execution prove that the conditional libc++ option crossed the exported-target boundary. No job, platform, warning gate, sanitizer, documentation check, or test was removed to obtain this pass.

Release boundary

The source tree satisfied the recorded v1.0 local acceptance checks, and source commit 58edaa86976ba510a38206f290f571705e813645 passed every required hosted job. This ledger update is a documentation-only successor. It must independently pass the same five-job workflow before the annotated v1.0.0 tag and source-only GitHub Release are created. At the time this ledger was authored, those two publication actions had not yet run; the GitHub tag and Releases pages are the authoritative post-ledger publication record.

After the ledger was finalized, the goal-owned goal2-*, retry-clock, analysis, Doxygen-probe, dependency-bootstrap, and validation-image build outputs were removed. The temporary pgmq-cpp-validation:ubuntu24 image and drive substitution were also removed. Earlier build/cache directories that predated this goal were left untouched.

Post-release-candidate worker-start and pool-return follow-up

On 2026-07-27, a source review identified two exceptional resource-failure paths that the release-candidate suite did not distinguish.

For partial worker startup, a build-test-only one-shot thread-launch failpoint was added. With the old lifecycle logic still present, failure after one successful launch followed by a second start() produced:

[FAIL] worker start retry rebuilds per-run state after launch failure:
retried runtime did not dispatch a task
0/1 tests passed

The repair rebuilds all per-run queue and thread state before an accepted retry. The same integration test then passed at two different partial-launch indices (after one and after three successful launches). The test starts the same runtime again, sends a real PGMQ message, requires exactly one handler call, observes an empty queue, and requires a clean shutdown.

The connection-pool follow-up reserves pool_size idle slots during construction. Its unit test checks that the storage capacity covers every possible healthy connection return, so release() cannot allocate while executing through its noexcept lease-destruction path.

Fresh Windows MSVC 19.41 Release evidence used both static build/next-step-pgmq and shared build/next-step-pgmq-shared builds with /W4 /WX. Each complete CTest run passed 8/8, including the installed consumer, real PostgreSQL 18 SDK and Worker suites, deterministic crash recovery, multiprocess behavior, and fixture cleanup. The shared build also proved that the test-only launch seam links correctly across the DLL boundary.

A Linux GCC 13.4 Debug build then ran with ASan and UBSan, leak detection, strict string checks, stack traces, and halt-on-error enabled. The first attempt correctly failed at compile time because the new internal pool test did not inherit the private PostgreSQL header directory on Linux. After the test target declared that include dependency, the sanitizer build passed, the unit executable passed 14/14, and the real-PostgreSQL filtered partial-start retry test passed 1/1. No sanitizer diagnostic was emitted.

These results are local follow-up evidence. They do not claim that a new tag, GitHub Release, or hosted workflow was created or run.