fix: low-level correctness sweep (audit group C)

Digest references work end to end: split_image splits name@sha256:hex
at the '@' (digest in the tag slot; trailing ':' or '@' normalizes to
latest), and the new join_image re-attaches digests with '@' at every
re-join site (create-spec reference, exists/inspect, pull ?tag= already
accepted digests). The near-duplicate split_image_ref is deleted; its
one caller (the sshd override) now takes digest spellings too.

New detail::saturated_add clamps every user-sized budget at
time_point::max() instead of overflowing the clock rep (UB whose
typical wrap failed healthy starts instantly - and only on the stdlib
whose rep is fine enough, the MSVC-100ns-vs-libstdc++-1ns trap):
wait_until_ready, clamped_wait_plan, the poll-loop sleep legs, the
three transport connect deadlines, compose's probe deadline, and the
Kafka/Mongo hook phase budgets.

url_encode drops locale-sensitive isalnum for an explicit ASCII test;
create_container's lazy pull is gated on a case-insensitive "no such
image" 404 body (a missing network also 404s - no more spurious
re-pull with the error pinned on the wrong resource); the tar write
path tolerates ARCHIVE_WARN like the read paths; sha256 gains the
55/56/64-byte padding-boundary vectors (NIST two-block included).

Pipeline: MSVC 563 units, Linux core integration 135 pass/44 skip,
module suite 34/34, WSL gcc 557 units, clang-tidy (17 TUs) and
clang-format clean. Opus review: SHIP; both recommendations applied
(case-insensitive pull gate, dead <utility> include).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0141x8KrNdD9NfmCh1vSMbpg

Author: cppudge

docs/TODO.md

@@ -139,8 +139,8 @@ loopback/named-pipe servers live in tests/unit/{LoopbackServer,PipeServer}.hpp.
   utility image (2026-07-11); still out of scope by design: `GenericBuildableImage` output
   (the daemon resolves `FROM`), compose YAML services (the file is the user's), and raw
   `DockerClient` calls. The custom `with_image_name_substitutor` remains `GenericImage`-only.
-  Utility-image overrides take `name[:tag]` references — digest (`@sha256:...`) spellings
-  don't fit the sshd sidecar's name:tag builder. The age-based pull policy (2026-07-11)
+  Utility-image overrides take `name[:tag]` or `name@sha256:...` references (digest
+  spellings work since the 2026-07-12 split/join unification: a digest re-joins with '@'). The age-based pull policy (2026-07-11)
   applies to `GenericImage` runs only (utility images and compose stay Default/explicit).
 - **Host access residuals** — remote forwards are never cancelled once added; the
   tunnel pump wakes every 100ms even when idle (fine for test traffic).

docs/feature-notes.md

@@ -299,8 +299,12 @@ says nothing about freshness, so derive the tag from a hash of the build inputs
 change. `GenericImage::inspect(name, tag)` / `img.inspect()` (backed by
 `DockerClient::inspect_image[_raw]`, which also takes full references/digests) return a typed
 `ImageInspect` — id, repo tags/digests, created, os/arch, size, and the image config (labels,
-env, cmd, entrypoint, exposed ports, workdir, user); the instance form uses `image():tag()`
-verbatim, no substitutor. Built images are session-scoped: `build()` ships the managed-by /
+env, cmd, entrypoint, exposed ports, workdir, user); the instance form re-joins
+`image()`/`tag()` digest-aware, no substitutor. Digest-pinned references
+(`name@sha256:...`) work end to end (2026-07-12): `from_reference`/`with_image` split them
+at the '@' (the digest becomes the tag slot), and every re-join — the create-spec
+reference, the pull query (`?tag=` accepts a digest), the utility-image overrides — goes
+through the shared digest-aware `join_image` ('@', never ':'). Built images are session-scoped: `build()` ships the managed-by /
 session labels via `?labels=` (merged with the Dockerfile's own LABELs; on a duplicate key the
 query label wins, `docker build --label` parity) and boots the reaper, so Ryuk removes the
 image shortly after the process exits — base images and pulled layers are untouched. With the

src/Deadline.hpp

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <chrono>
+
+namespace testcontainers::detail {
+
+/// `at + delta` with saturation at `time_point::max()`. User-sized budgets
+/// ("wait forever" spelled as milliseconds::max(), hours(300000), ...) must
+/// clamp to the far future: the plain `+` is signed-integer overflow (UB),
+/// and the typical wrap lands the deadline in the PAST, timing a healthy
+/// wait out instantly. The overflow window is stdlib-dependent — MSVC's
+/// steady_clock rep ticks at 100ns while libstdc++'s at 1ns — so the same
+/// budget can be green on one toolchain and wrapped on the other; the
+/// comparison therefore happens in milliseconds, BEFORE any conversion to
+/// the clock's finer rep. A non-positive delta yields `at` unchanged (an
+/// already-due deadline).
+inline std::chrono::steady_clock::time_point saturated_add(std::chrono::steady_clock::time_point at,
+                                                           std::chrono::milliseconds delta) {
+    using clock = std::chrono::steady_clock;
+    if (delta <= std::chrono::milliseconds::zero()) {
+        return at;
+    }
+    // Truncation makes headroom conservative (never larger than the real
+    // room), so `delta < headroom` guarantees the converted add fits.
+    const auto headroom =
+        std::chrono::duration_cast<std::chrono::milliseconds>(clock::time_point::max() - at);
+    return delta >= headroom ? clock::time_point::max() : at + delta;
+}
+
+} // namespace testcontainers::detail

src/DockerComposeContainer.cpp

@@ -1,6 +1,7 @@
 #include "testcontainers/DockerComposeContainer.hpp"
 
 #include "Config.hpp"
+#include "Deadline.hpp"
 #include "HostAddress.hpp"
 #include "RandomHex.hpp"
 #include "Reaper.hpp"
@@ -604,8 +605,10 @@ void DockerComposeContainer::start() {
                 : get_service_port(exposed.service, exposed.instance, exposed.port);
         const std::string host = get_service_host(exposed.service);
 
-        // The same user-configurable timeout that governs compose's --wait.
-        const auto deadline = std::chrono::steady_clock::now() + wait_timeout_;
+        // The same user-configurable timeout that governs compose's --wait
+        // (saturated: a "wait forever"-sized value clamps, never wraps).
+        const auto deadline =
+            detail::saturated_add(std::chrono::steady_clock::now(), wait_timeout_);
         bool connected = false;
         while (std::chrono::steady_clock::now() < deadline) {
             if (detail::tcp_probe(host, host_port, detail::probe_budget(deadline))) {

src/GenericImage.cpp

@@ -26,11 +26,11 @@ GenericImage& GenericImage::with_image(const std::string& reference) {
 
 bool GenericImage::exists(const std::string& name, const std::string& tag) {
     DockerClient client = DockerClient::from_environment();
-    return client.image_exists(name + ":" + tag);
+    return client.image_exists(docker::join_image(name, tag));
 }
 
 ImageInspect GenericImage::inspect(const std::string& name, const std::string& tag) {
-    return DockerClient::from_environment().inspect_image(name + ":" + tag);
+    return DockerClient::from_environment().inspect_image(docker::join_image(name, tag));
 }
 
 ImageInspect GenericImage::inspect() const { return inspect(image_, tag_); }
@@ -48,7 +48,8 @@ ContainerRequest GenericImage::to_request() const {
 
     // Resolve the effective image reference: a custom substitutor overrides the
     // default env-prefix substitution (TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX).
-    const std::string raw_ref = image_ + ":" + tag_;
+    // join_image, not '+ ":" +': a digest tag re-attaches with '@'.
+    const std::string raw_ref = docker::join_image(image_, tag_);
     request.spec.image =
         substitutor_ ? substitutor_(raw_ref) : docker::substitute_image_name(raw_ref);
 

src/HostPortForwarding.cpp

@@ -24,7 +24,7 @@
 #include "Config.hpp"
 #include "RandomHex.hpp"
 #include "Runner.hpp"
-#include "docker/Auth.hpp" // split_image_ref (sshd.container.image override)
+#include "docker/ApiMapping.hpp" // split_image (sshd.container.image override)
 #include "testcontainers/Container.hpp"
 #include "testcontainers/ContainerRequest.hpp"
 #include "testcontainers/Error.hpp"
@@ -42,8 +42,8 @@ using asio::ip::tcp;
 /// openssh; its own entrypoint+command set ${USERNAME} (root) to ${PASSWORD}
 /// and run sshd in the foreground with GatewayPorts=yes. Overridable via env
 /// TESTCONTAINERS_SSHD_CONTAINER_IMAGE / properties key sshd.container.image
-/// (a name[:tag] reference); the hub prefix applies through GenericImage's
-/// default substitutor either way.
+/// (a name[:tag] or name@sha256:... reference); the hub prefix applies
+/// through GenericImage's default substitutor either way.
 constexpr const char* kSshdImage = "testcontainers/sshd";
 constexpr const char* kSshdTag = "1.3.0";
 
@@ -53,7 +53,7 @@ std::pair<std::string, std::string> sshd_image_and_tag() {
     if (!override_ref) {
         return {kSshdImage, kSshdTag};
     }
-    return docker::split_image_ref(*override_ref);
+    return docker::split_image(*override_ref);
 }
 
 /// Per-direction buffer cap per forwarded connection. When a buffer is full

src/WaitStrategies.cpp

@@ -16,6 +16,7 @@
 #include <boost/beast/core/tcp_stream.hpp>
 #include <boost/beast/http.hpp>
 
+#include "Deadline.hpp"
 #include "HostAddress.hpp"
 #include "docker/Ports.hpp"
 #include "testcontainers/ContainerPort.hpp"
@@ -165,8 +166,9 @@ void wait_for_log(DockerClient& client, const std::string& id, const wait_for::L
         // FollowEnd::StreamEnded: the container stopped. Its logs are final
         // unless it restarts (restart policy), so pause briefly and re-follow;
         // an expired budget lands in the final snapshot check above.
-        std::this_thread::sleep_until(std::min(Clock::now() + std::chrono::milliseconds(200),
-                                               deadline + std::chrono::milliseconds(1)));
+        std::this_thread::sleep_until(
+            std::min(Clock::now() + std::chrono::milliseconds(200),
+                     detail::saturated_add(deadline, std::chrono::milliseconds(1))));
     }
 }
 
@@ -486,8 +488,11 @@ void wait_for_command(DockerClient& client, const std::string& id, const wait_fo
         if (Clock::now() >= deadline) {
             throw timeout_error();
         }
+        // Both legs saturate: `interval` is a user knob (poll_interval) and
+        // `deadline` may already sit at the clamped far future.
         std::this_thread::sleep_until(
-            std::min(Clock::now() + interval, deadline + std::chrono::milliseconds(1)));
+            std::min(detail::saturated_add(Clock::now(), interval),
+                     detail::saturated_add(deadline, std::chrono::milliseconds(1))));
     }
 }
 
@@ -508,7 +513,11 @@ void wait_until_ready(DockerClient& client, const std::string& id,
     // and docs/TODO.md for the analysis.
     const DockerClient::Session session(client);
 
-    const Clock::time_point deadline = Clock::now() + timeout;
+    // saturated_add, not '+': the startup timeout is a raw user knob, and a
+    // "wait forever"-sized value must clamp instead of wrapping into the past
+    // (which failed healthy starts instantly — and only on the stdlib whose
+    // clock rep is fine enough to overflow).
+    const Clock::time_point deadline = detail::saturated_add(Clock::now(), timeout);
 
     for (const WaitFor& w : waits) {
         std::visit(

src/WaitStrategies.hpp

@@ -8,6 +8,7 @@
 #include <utility>
 #include <vector>
 
+#include "Deadline.hpp"
 #include "testcontainers/WaitFor.hpp"
 
 namespace testcontainers {
@@ -58,7 +59,9 @@ struct ClampedWaitPlan {
 inline ClampedWaitPlan clamped_wait_plan(std::chrono::steady_clock::time_point now,
                                          std::chrono::milliseconds value,
                                          std::chrono::steady_clock::time_point deadline) {
-    const std::chrono::steady_clock::time_point wake = now + value;
+    // saturated_add, not '+': a milliseconds::max()-sized duration must clamp
+    // to the far future (and so time out), not overflow into the past.
+    const std::chrono::steady_clock::time_point wake = detail::saturated_add(now, value);
     return {wake < deadline ? wake : deadline, wake > deadline};
 }
 

src/docker/ApiMapping.cpp

@@ -927,13 +927,33 @@ void throw_if_pull_error(const std::string& pull_stream, const std::string& imag
 
 std::pair<std::string, std::string> split_image(const std::string& image) {
     const std::size_t slash = image.rfind('/');
+    const std::size_t at = image.rfind('@');
+    if (at != std::string::npos && (slash == std::string::npos || at > slash)) {
+        // Digest reference. The daemon accepts the digest wherever a tag
+        // goes (pull's ?tag= parameter takes "Tag or digest"); only the
+        // re-join differs — join_image uses '@'. A bare trailing '@' is
+        // normalized like a bare trailing ':'.
+        if (at + 1 == image.size()) {
+            return {image.substr(0, at), "latest"};
+        }
+        return {image.substr(0, at), image.substr(at + 1)};
+    }
     const std::size_t colon = image.rfind(':');
     if (colon != std::string::npos && (slash == std::string::npos || colon > slash)) {
+        if (colon + 1 == image.size()) {
+            return {image.substr(0, colon), "latest"}; // "redis:" means "redis"
+        }
         return {image.substr(0, colon), image.substr(colon + 1)};
     }
     return {image, "latest"};
 }
 
+std::string join_image(const std::string& name, const std::string& tag) {
+    // A legal tag ([A-Za-z0-9_][A-Za-z0-9._-]{0,127}) cannot contain ':'; a
+    // digest ("sha256:<hex>") always does.
+    return tag.find(':') != std::string::npos ? name + "@" + tag : name + ":" + tag;
+}
+
 std::string build_build_query(const BuildOptions& options,
                               const std::function<std::string(const std::string&)>& encode) {
     std::string query;

src/docker/ApiMapping.hpp

@@ -142,10 +142,19 @@ std::string expect_string_field(const std::string& body, const char* field,
 /// throw DockerError if it reports an error (Docker returns HTTP 200 even then).
 void throw_if_pull_error(const std::string& pull_stream, const std::string& image);
 
-/// Split "name[:tag]" into {name, tag}; tag defaults to "latest". Handles a
-/// registry host with a port (e.g. "my-reg:5000/img" -> {"my-reg:5000/img", "latest"}).
+/// Split "name[:tag]" or "name@sha256:<hex>" into {name, tag-or-digest}: the
+/// tag separator is the last ':' after the last '/' (a registry host:port is
+/// not a tag), an '@' after the last '/' starts a digest (returned verbatim,
+/// "sha256:..."), and no tag — a bare trailing ':' included — means "latest".
+/// `join_image` is the inverse; every re-join must go through it, since a
+/// digest re-attaches with '@', not ':'.
 std::pair<std::string, std::string> split_image(const std::string& image);
 
+/// Re-join a split_image pair into a reference the daemon accepts: '@' when
+/// the tag is a digest, ':' otherwise. (A legal tag cannot contain ':'; a
+/// digest always does.)
+std::string join_image(const std::string& name, const std::string& tag);
+
 /// Build the query string (incl. leading '?') for `POST /build`: t, dockerfile,
 /// nocache, pull, target (when set), and buildargs / labels (JSON objects,
 /// percent-encoded). `encode` is the caller's URL-encoder. Unit-testable