test(database): build the timestamp round-trip diagnostic without casts (#3716)

On BoxLang + Oracle, TimestampRoundTripSpec errored with "Can't cast
oracle.sql.TIMESTAMP to a string". Its failure message is evaluated on
every run, pass or fail, and it concatenated the raw driver value.

The normalizer itself is sound: a new spec feeds it a real
oracle.sql.TIMESTAMP and it passes on BoxLang. The fix is a
$describeDbValue() helper that prints any value (simple, struct,
component, Java object) without casting, used by the spec's message.

Fixes #3714

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: bpamiri

vendor/wheels/global/util.cfm

@@ -342,6 +342,46 @@
 	}
 
 
+	/**
+	 * Internal function.
+	 * A printable description of any value read back from a database, for
+	 * diagnostics. Never casts a driver object to a string: BoxLang throws
+	 * "Can't cast oracle.sql.TIMESTAMP to a string" on concatenation, which
+	 * turned a failure message into the failure (#3714).
+	 */
+	public string function $describeDbValue(required any value) {
+		if (IsSimpleValue(arguments.value)) {
+			try {
+				return "" & arguments.value;
+			} catch (any e) {
+				// Reported as simple but not castable; describe it by type below.
+			}
+		}
+		if (IsStruct(arguments.value) && !IsObject(arguments.value)) {
+			return "[struct]";
+		}
+		if (IsArray(arguments.value)) {
+			return "[array]";
+		}
+		if (IsQuery(arguments.value)) {
+			return "[query]";
+		}
+		try {
+			local.meta = GetMetadata(arguments.value);
+			if (IsStruct(local.meta) && StructKeyExists(local.meta, "fullname")) {
+				return "[component " & local.meta.fullname & "]";
+			}
+		} catch (any e) {
+			// Not a component.
+		}
+		try {
+			return "[object " & arguments.value.getClass().getName() & "]";
+		} catch (any e) {
+			return "[unprintable value]";
+		}
+	}
+
+
 	/**
 	 * Internal function for `$normalizeDbTimestamp()`. Converts a
 	 * `java.util.Date` into a CFML date through `java.util.Calendar`, so the

vendor/wheels/tests/specs/database/TimestampRoundTripSpec.cfc

@@ -62,16 +62,17 @@ component extends="wheels.WheelsTest" {
 				// contract (#3649).
 				var normalized = application.wo.$normalizeDbTimestamp(readBack);
 				var shape = IsDate(normalized) ? "date" : "neither";
-				var valueClass = IsObject(readBack) ? readBack.getClass().getName() : "not-an-object";
-
 				// Report the value and its Java class, not just the verdict.
 				// "Expected [NO] to be true" is what the downstream failures say,
-				// and it names nothing at all.
+				// and it names nothing at all. The message is built on every run,
+				// pass or fail, so it must never cast the raw driver object: on
+				// BoxLang, concatenating an oracle.sql.TIMESTAMP throws (#3714).
+				var described = application.wo.$describeDbValue(readBack);
 				expect(shape).notToBe(
 					"neither",
 					"A cf_sql_timestamp round-tripped as something $secondsSince() cannot "
 					& "read: wrote [" & DateTimeFormat(written, "yyyy-mm-dd HH:nn:ss")
-					& "], read back [" & readBack & "] of class [" & valueClass & "]. Every "
+					& "], read back " & described & ". Every "
 					& "framework path that stores a timestamp and later measures elapsed time "
 					& "against it — RateLimiter's token bucket, the migrator's applied_at — is "
 					& "unreliable here."
@@ -87,7 +88,7 @@ component extends="wheels.WheelsTest" {
 					120,
 					"The stored timestamp came back as a #shape# that does not resolve to "
 					& "the time written: wrote [" & DateTimeFormat(written, "yyyy-mm-dd HH:nn:ss")
-					& "], read back [" & readBack & "] of class [" & valueClass & "]. "
+					& "], read back " & described & ". "
 					& "$secondsSince() would report " & elapsed & "s elapsed where "
 					& expected & "s is correct."
 				);

vendor/wheels/tests/specs/global/DbTimestampNormalizationSpec.cfc

@@ -59,6 +59,34 @@ component extends="wheels.WheelsTest" {
 				expect(DateDiff("s", normalized, g.$normalizeDbTimestamp(millis))).toBe(0);
 			});
 
+			it("normalizes a real oracle.sql.TIMESTAMP when the Oracle driver is loaded (##3714)", () => {
+				// The stub above pins the timestampValue() bridge; this pins the real
+				// driver class, which BoxLang hands back for a cf_sql_timestamp column.
+				var state = {value = ""};
+				try {
+					state.value = CreateObject("java", "oracle.sql.TIMESTAMP").init(
+						CreateObject("java", "java.sql.Timestamp").init(JavaCast("long", millis))
+					);
+				} catch (any e) {
+					state.value = "";
+				}
+				if (IsSimpleValue(state.value)) {
+					skip("oracle.sql.TIMESTAMP is not on this engine's classpath (runs on the Oracle legs).");
+					return;
+				}
+				var normalized = g.$normalizeDbTimestamp(state.value);
+				expect(IsDate(normalized)).toBeTrue();
+				expect(DateDiff("s", normalized, g.$normalizeDbTimestamp(millis))).toBe(0);
+				// Concatenating the raw object throws on BoxLang; the describer must not.
+				expect(g.$describeDbValue(state.value)).toInclude("oracle.sql.TIMESTAMP");
+			});
+
+			it("describes any value for a diagnostic without casting it (##3714)", () => {
+				expect(g.$describeDbValue("2026-07-25 10:20:00")).toBe("2026-07-25 10:20:00");
+				expect(g.$describeDbValue(new wheels.tests._assets.db.OracleTimestampStub(millis))).toInclude("OracleTimestampStub");
+				expect(g.$describeDbValue({a = 1})).toBe("[struct]");
+			});
+
 			it("accepts fractional-second datetime strings", () => {
 				var normalized = g.$normalizeDbTimestamp("2026-07-25 10:20:00.205");
 				expect(IsDate(normalized)).toBeTrue();