From 2456905c973fedc206b9780aa700cf7c9d0298fb Mon Sep 17 00:00:00 2001
From: Stefan Steiner <ssteiner@tableau.com>
Date: Tue, 16 Jun 2026 16:05:38 -0700
Subject: [PATCH 1/2] docs(api): note _as_params as the binding target for
 query_as! (#137)

query_as! / query_scalar! validate SQL and accept $N args but the
QueryAs/QueryScalar runtime builders don't yet bind them (params stored
as debug strings; fetch_* forward to the non-param fetch_*_as). Point
the dead-code comment and a TODO at fetch_*_as_params (added in #137) as
the primitive that finishes parameter binding.
---
 hyperdb-api/src/query_as.rs | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/hyperdb-api/src/query_as.rs b/hyperdb-api/src/query_as.rs
index e75f856..b36f399 100644
--- a/hyperdb-api/src/query_as.rs
+++ b/hyperdb-api/src/query_as.rs
@@ -14,9 +14,17 @@ use crate::{Connection, FromRow, Result, RowValue};
 #[derive(Debug)]
 pub struct QueryAs<T> {
     sql: String,
-    // Bind parameters are stored as formatted strings for now. Full typed
-    // parameter support (ToSqlParam) is wired in Milestone B.
-    #[allow(dead_code, reason = "full parameter binding wired in Milestone B (W3)")]
+    // Bind parameters are stored as formatted strings for now — the macro
+    // accepts `$N` args and validates the SQL, but binding is not yet wired
+    // (the `fetch_*` methods below forward to the NON-param `fetch_*_as`).
+    //
+    // To finish this: change `params` to hold `ToSqlParam` values and route
+    // through `Connection::fetch_*_as_params` (added in issue #137 — the
+    // parameterized FromRow methods are exactly the primitive this needs).
+    #[allow(
+        dead_code,
+        reason = "typed parameter binding not yet wired — see issue #137"
+    )]
     params: Vec<String>,
     _phantom: PhantomData<fn() -> T>,
 }
@@ -42,6 +50,8 @@ impl<T: FromRow> QueryAs<T> {
     /// Returns a `hyperdb_api::Error` on connection failure, SQL error, or
     /// row-mapping failure.
     pub fn fetch_all(self, conn: &Connection) -> Result<Vec<T>> {
+        // TODO(#137): forward to `conn.fetch_all_as_params(&self.sql, &params)`
+        // once `params` holds `ToSqlParam` values, to actually bind `$N` args.
         conn.fetch_all_as(&self.sql)
     }
 

From 425809c98a097720607d9b548d80d6ecfb6378fd Mon Sep 17 00:00:00 2001
From: Stefan Steiner <ssteiner@tableau.com>
Date: Tue, 16 Jun 2026 16:09:38 -0700
Subject: [PATCH 2/2] docs(api): align all query_as/query_scalar param comments
 (#137)

Remove stale 'W3' and 'future milestone' phrasing from QueryAs::new doc
and QueryScalar::params allow-reason. Both now point at issue #137 and
the _as_params delegation target, consistent with the QueryAs::params
comment updated in the prior commit.
---
 hyperdb-api/src/query_as.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/hyperdb-api/src/query_as.rs b/hyperdb-api/src/query_as.rs
index b36f399..0c62870 100644
--- a/hyperdb-api/src/query_as.rs
+++ b/hyperdb-api/src/query_as.rs
@@ -34,7 +34,8 @@ impl<T: FromRow> QueryAs<T> {
     /// for direct use.
     ///
     /// `params` accepts `&dyn std::fmt::Debug` so the macro can pass any bind
-    /// arguments through — the actual typed binding will be tightened in W3.
+    /// arguments through — typed binding via `ToSqlParam` is not yet wired
+    /// (see the `TODO(#137)` on `fetch_all` below).
     pub fn new(sql: &str, params: &[&dyn std::fmt::Debug]) -> Self {
         Self {
             sql: sql.to_owned(),
@@ -91,9 +92,12 @@ impl<T: FromRow> QueryAs<T> {
 #[derive(Debug)]
 pub struct QueryScalar<T> {
     sql: String,
+    // Same gap as `QueryAs::params` — the macro validates the SQL and
+    // accepts args, but binding isn't wired yet. Route through
+    // `fetch_scalar_params` (or equivalent) once it exists.
     #[allow(
         dead_code,
-        reason = "typed parameter binding wired in a future milestone"
+        reason = "typed parameter binding not yet wired — see issue #137"
     )]
     params: Vec<String>,
     _phantom: PhantomData<fn() -> T>,