chore(compile-time): add opt-in compile-time SQL validation (query_as!, derive(Table), VS Code squigglies)

.github/workflows/ci.yml

@@ -77,10 +77,24 @@ jobs:
           # See fmt job for rationale; clippy enforces -D warnings via
           # the explicit `-- -D warnings` arg below, not via env.
           rustflags: ""
+      - name: Cache hyperd binary
+        # --all-features enables the compile-time feature, which starts an
+        # embedded Hyper instance inside the proc-macro host during clippy.
+        # hyperd must be present or the proc-macro panics.
+        id: hyperd-cache
+        uses: actions/cache@v5
+        with:
+          path: .hyperd
+          key: hyperd-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('hyperdb-bootstrap/hyperd-version.toml') }}
+      - name: Download hyperd
+        if: steps.hyperd-cache.outputs.cache-hit != 'true'
+        run: cargo run --release -p hyperdb-bootstrap --bin hyperdb-bootstrap -- download
       - name: Clippy (workspace, all targets)
         # Every crate in the workspace is linted under the Microsoft Rust
         # Guidelines config in `[workspace.lints]` (see Cargo.toml and
         # docs/RUST_GUIDELINES.md). Warnings are treated as errors.
+        env:
+          HYPERD_PATH: ${{ github.workspace }}/.hyperd/current
         run: cargo clippy --workspace --all-targets --all-features -- -D warnings
 
   test:
@@ -200,16 +214,16 @@ jobs:
   publish-dry-run:
     # Catches Cargo.toml metadata regressions (missing license, bad
     # include paths, etc.) on the subset of crates that have no
-    # workspace deps — those are the only ones `cargo publish --dry-run`
-    # can check before anything's on crates.io. The other crates
-    # (hyperdb-api-core, hyperdb-api-salesforce, hyperdb-api, hyperdb-mcp)
-    # resolve their path+version deps against the live index, which can't
-    # succeed until those deps are themselves published. (Note:
-    # hyperdb-api-core has an optional workspace dep on
-    # hyperdb-api-salesforce via its `salesforce-auth` feature, which
-    # triggers the same path-resolution failure even though the dep is
-    # optional.) They're exercised end-to-end by release.yml at tag
-    # time, when the whole wave ships together.
+    # unresolvable path deps before the full wave ships.
+    # Excluded from dry-run (resolved only at release time):
+    #   hyperdb-api-core, hyperdb-api-salesforce, hyperdb-api, hyperdb-mcp:
+    #     path+version deps on workspace siblings not yet on crates.io.
+    #   hyperdb-api-derive: now has an optional path dep on
+    #     hyperdb-compile-check, which is not a workspace member and not on
+    #     crates.io until the release wave lands. Even optional deps are
+    #     resolved by `cargo publish --dry-run` during verification.
+    #   hyperdb-compile-check: depends on hyperdb-api (not yet published).
+    # All of the above are exercised end-to-end by release.yml at tag time.
     name: publish dry-run
     runs-on: ubuntu-latest
     timeout-minutes: 15
@@ -223,9 +237,12 @@ jobs:
           cache-key: publish-dry-run
           rustflags: ""
       - run: |
-          cargo publish -p hyperdb-bootstrap     --dry-run
-          cargo publish -p sea-query-hyperdb     --dry-run
-          cargo publish -p hyperdb-api-derive    --dry-run
+          cargo publish -p hyperdb-bootstrap  --dry-run
+          cargo publish -p sea-query-hyperdb  --dry-run
+          # hyperdb-api-derive excluded: has an optional path dep on
+          # hyperdb-compile-check which isn't on crates.io until the full
+          # release wave lands. Cargo resolves optional deps during dry-run
+          # verification regardless of whether the feature is enabled.
 
   deny:
     # Enforces license allowlist, advisory ignore list, and banned-source

.github/workflows/release.yml

@@ -173,6 +173,8 @@ jobs:
       - name: Confirm tag matches workspace version
         # All publishable crates are in lockstep. Use hyperdb-api-core as
         # the bellwether (it's the foundation every other crate depends on).
+        # hyperdb-compile-check is outside the workspace but must also be
+        # in lockstep — check its version separately via its own Cargo.toml.
         env:
           EXPECTED: ${{ steps.tag.outputs.version }}
         run: |
@@ -183,6 +185,15 @@ jobs:
             echo "::error::Tag version ($EXPECTED) does not match hyperdb-api-core Cargo.toml ($ACTUAL). Bump all workspace Cargo.tomls to match the tag before releasing." >&2
             exit 1
           fi
+          # hyperdb-compile-check lives outside the workspace; check its
+          # version via cargo metadata targeted at its own Cargo.toml.
+          CC_ACTUAL=$(cargo metadata --no-deps --format-version 1 \
+            --manifest-path hyperdb-compile-check/Cargo.toml \
+            | jq -r '.packages[] | select(.name=="hyperdb-compile-check") | .version')
+          if [[ "$EXPECTED" != "$CC_ACTUAL" ]]; then
+            echo "::error::Tag version ($EXPECTED) does not match hyperdb-compile-check/Cargo.toml ($CC_ACTUAL). Bump it to match before releasing." >&2
+            exit 1
+          fi
 
       - name: Publish in dependency order
         env:
@@ -215,12 +226,27 @@ jobs:
           # - hyperdb-api: depends on hyperdb-api-core AND
           #   hyperdb-api-derive (=X.Y.Z strict pin → derive must be
           #   on the index when hyperdb-api builds).
+          # - hyperdb-compile-check: depends on hyperdb-api; outside the
+          #   workspace (avoids dep cycle) but published in lockstep.
+          #   Uses --manifest-path since it's not a workspace member.
           # - hyperdb-mcp, hyperdb-bootstrap, sea-query-hyperdb: depend
           #   on hyperdb-api / hyperdb-api-core; publish last.
           publish hyperdb-api-salesforce
           publish hyperdb-api-derive
           publish hyperdb-api-core
           publish hyperdb-api
+          # hyperdb-compile-check is not a workspace member; publish via manifest path
+          echo "::group::Publishing hyperdb-compile-check"
+          if ! cargo publish --manifest-path hyperdb-compile-check/Cargo.toml 2>&1 | tee /tmp/publish_out; then
+            if grep -q "already exists on" /tmp/publish_out; then
+              echo "::warning::hyperdb-compile-check already published — skipping"
+            else
+              echo "::endgroup::"
+              exit 1
+            fi
+          fi
+          echo "::endgroup::"
+          sleep 45
           publish hyperdb-mcp
           publish hyperdb-bootstrap
           publish sea-query-hyperdb

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  // Enable the compile-time feature on hyperdb-api-derive so rust-analyzer
+  // uses the real validation path (not the pass-through stub).
+  // NOTE: this is a flat array of `package/feature` strings, NOT a map.
+  "rust-analyzer.cargo.features": ["hyperdb-api-derive/compile-time"],
+
+  // Make the hyperd binary discoverable by the proc-macro host that RA spawns.
+  // The macro calls HyperProcess::new(None, ...) which looks for HYPERD_PATH
+  // or walks up from CWD for .hyperd/current/hyperd.
+  "rust-analyzer.server.extraEnv": {
+    "HYPERD_PATH": "${workspaceFolder}/.hyperd/current"
+  }
+}

Cargo.toml

@@ -10,6 +10,20 @@ members = [
     "hyperdb-bootstrap",
     "sea-query-hyperdb",
 ]
+# Exclude hyperdb-compile-check from the workspace resolver: it has its own
+# [workspace] declaration to avoid the Cargo cycle that would arise from
+# hyperdb-api → hyperdb-api-derive → hyperdb-compile-check → hyperdb-api.
+# See the comment block below for full rationale.
+exclude = ["hyperdb-compile-check"]
+
+# hyperdb-compile-check is intentionally NOT a workspace member.
+# It depends on hyperdb-api, which depends on hyperdb-api-derive, which
+# optionally depends on hyperdb-compile-check. Adding it to the workspace
+# would create a cycle that Cargo rejects even for optional deps.
+# It lives in the repository as a standalone crate with its own Cargo.toml
+# and is referenced as a path dep by hyperdb-api-derive when the
+# compile-time feature is enabled. CI builds it explicitly via
+# `cargo build --manifest-path hyperdb-compile-check/Cargo.toml`.
 
 [workspace.package]
 version = "0.3.1"
@@ -52,6 +66,7 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 url = "2.5"
 chrono = { version = "0.4", default-features = false, features = ["std", "clock"] }
+parking_lot = "0.12"
 # hyperd-bootstrap dependencies
 zip = { version = "8", default-features = false, features = ["deflate"] }
 toml = "1.1"

hyperdb-api-derive/Cargo.toml

@@ -14,10 +14,25 @@ categories = ["database"]
 [lib]
 proc-macro = true
 
+[features]
+# Enable compile-time SQL validation via query_as! and derive(Table) #[hyperdb(register)].
+# Off by default. When enabled, hyperdb-compile-check is pulled in as a dep.
+# The dep cycle (hyperdb-api → hyperdb-api-derive → hyperdb-compile-check → hyperdb-api)
+# is broken by removing hyperdb-api-derive from hyperdb-api's dependencies entirely.
+# Users of derive macros add hyperdb-api-derive directly.
+compile-time = ["dep:hyperdb-compile-check"]
+
 [dependencies]
 syn = { version = "2", features = ["full"] }
 quote = "1"
 proc-macro2 = "1"
+hyperdb-compile-check = { path = "../hyperdb-compile-check", version = "=0.3.1", optional = true }
+
+[dev-dependencies]
+# x-release-please-start-version
+hyperdb-api = { path = "../hyperdb-api", version = "=0.3.1" }
+# x-release-please-end
+trybuild = { version = "1", features = ["diff"] }
 
 [lints]
 workspace = true