feat(rusty-red): add product query and graph cache surfaces

Author: Travis-Gilbert

README.md

@@ -32,9 +32,9 @@ This builds an `abi3-py312` wheel and installs it into the active Python environ
 
 Rusty Red is the productized THG runtime profile: it keeps the THG command model
 for existing harness flows while adding first-class graph node, edge, adjacency,
-exact scalar property index, stats, verify, and MCP routes. By default, it runs
-in `RUSTY_RED_MODE=embedded` with RedCore RAM-first storage and local AOF/snapshot
-persistence.
+exact scalar property index, GraphCache, stats, verify, and MCP routes. By
+default, it runs in `RUSTY_RED_MODE=embedded` with RedCore RAM-first storage and
+local AOF/snapshot persistence.
 
 It is not a raw Redis protocol, RedisGraph compatibility layer, FalkorDB
 replacement, or complete OpenCypher/GQL engine yet. `RUSTY_RED_MODE=redis` keeps
@@ -78,9 +78,21 @@ GET  /ready
 GET  /openapi.json
 GET  /.well-known/mcp/thg.json
 POST /mcp
+POST /v1/command
+POST /v1/batch
+POST /v1/query
+POST /v1/cypher
+POST /v1/cypher/explain
+POST /v1/cache/put
+POST /v1/cache/get
+POST /v1/cache/check
+POST /v1/cache/explain
+POST /v1/cache/invalidate
+POST /v1/cache/stats
 POST /v1/tenants/{tenant_id}/command
 POST /v1/tenants/{tenant_id}/batch
 GET  /v1/tenants/{tenant_id}/runs/{run_id}
+POST /v1/tenants/{tenant_id}/graph/query
 POST /v1/tenants/{tenant_id}/graph/nodes
 POST /v1/tenants/{tenant_id}/graph/nodes/query
 GET  /v1/tenants/{tenant_id}/graph/nodes/{node_id}
@@ -102,6 +114,12 @@ records, exact scalar property indexes, adjacency traversal, and verification
 through the existing THG command surface instead of depending on a separate
 runtime name. In this slice, run/context state commands remain Redis-mode.
 
+The public query surface is now split cleanly:
+
+- `/v1/query` is the product-facing native subset for `node_match` and `neighbors`.
+- `/v1/cypher` and `/v1/cypher/explain` are the first read-only OpenCypher-compatible subset.
+- `/v1/tenants/{tenant_id}/graph/query` remains the older debug bridge and should not be treated as the product route.
+
 The OpenAPI document is served at `/openapi.json`. It exists because Rusty Red
 is exposed through HTTP and MCP even though the underlying storage engine is a
 database-style service. The OpenAPI contract is for the HTTP API; MCP tool,
@@ -112,8 +130,10 @@ Railway template readiness follows the public template guidance: use a GitHub
 source repo, keep the service root minimal, set `/ready` as the health check,
 wire Redis only for explicit `RUSTY_RED_MODE=redis` deployments through private
 networking/reference variables, attach persistent storage to stateful dependencies,
-generate any public-ingress tokens with Railway template variable functions, and
-replace the badge placeholder above once Railway assigns the final template URL.
+set `RUSTY_RED_REQUIRE_VOLUME=true` for embedded Railway deployments so `/ready`
+fails when the mounted volume is absent, generate any public-ingress tokens with
+Railway template variable functions, and replace the badge placeholder above once
+Railway assigns the final template URL.
 
 Railway can deploy this directory directly:
 

crates/thg-product-server/src/config.rs

@@ -34,6 +34,8 @@ pub struct Config {
     pub port: u16,
     pub storage_mode: StorageMode,
     pub data_dir: String,
+    pub require_volume: bool,
+    pub volume_available: bool,
     pub durability: RedCoreDurability,
     pub snapshot_interval_writes: u64,
     pub strict_acid: bool,
@@ -71,15 +73,31 @@ impl Config {
         let storage_mode = env_first(&["RUSTY_RED_MODE", "THG_PRODUCT_STORE"])
             .map(|value| StorageMode::parse(&value))
             .unwrap_or(StorageMode::Embedded);
+        let railway_volume_mount_path = env::var("RAILWAY_VOLUME_MOUNT_PATH")
+            .ok()
+            .filter(|value| !value.trim().is_empty());
         let data_dir = env_first(&["RUSTY_RED_DATA_DIR", "THG_PRODUCT_DATA_DIR"])
-            .or_else(|_| env::var("RAILWAY_VOLUME_MOUNT_PATH"))
+            .or_else(|_| {
+                railway_volume_mount_path
+                    .clone()
+                    .ok_or(env::VarError::NotPresent)
+            })
             .unwrap_or_else(|_| {
                 if railway_port.is_some() {
                     "/app/data/rusty-red".to_string()
                 } else {
                     "data/rusty-red".to_string()
                 }
             });
+        let require_volume = env_bool(
+            &["RUSTY_RED_REQUIRE_VOLUME", "THG_PRODUCT_REQUIRE_VOLUME"],
+            railway_port.is_some(),
+        );
+        let volume_available = railway_volume_mount_path.is_some()
+            || env_bool(
+                &["RUSTY_RED_VOLUME_MOUNTED", "THG_PRODUCT_VOLUME_MOUNTED"],
+                false,
+            );
         let durability = env_first(&["RUSTY_RED_DURABILITY", "THG_PRODUCT_DURABILITY"])
             .map(|value| RedCoreDurability::parse(&value))
             .unwrap_or(RedCoreDurability::AofEverysec);
@@ -139,6 +157,8 @@ impl Config {
             port,
             storage_mode,
             data_dir,
+            require_volume,
+            volume_available,
             durability,
             snapshot_interval_writes,
             strict_acid,
@@ -164,6 +184,15 @@ impl Config {
     }
 
     pub fn validate(&self) -> Result<(), String> {
+        if self.storage_mode == StorageMode::Embedded
+            && self.require_volume
+            && !self.volume_available
+        {
+            return Err(
+                "RUSTY_RED_REQUIRE_VOLUME=true requires RAILWAY_VOLUME_MOUNT_PATH or RUSTY_RED_VOLUME_MOUNTED=true"
+                    .to_string(),
+            );
+        }
         if !self.strict_acid {
             return Ok(());
         }
@@ -228,6 +257,8 @@ mod tests {
             port: 8380,
             storage_mode: StorageMode::Embedded,
             data_dir: "data/rusty-red".to_string(),
+            require_volume: false,
+            volume_available: false,
             durability: RedCoreDurability::AofAlways,
             snapshot_interval_writes: 1_000,
             strict_acid: true,
@@ -260,4 +291,22 @@ mod tests {
     fn strict_acid_config_accepts_single_writer_serializable_embedded() {
         assert_eq!(base_config().validate(), Ok(()));
     }
+
+    #[test]
+    fn embedded_config_rejects_missing_required_volume() {
+        let mut config = base_config();
+        config.require_volume = true;
+        config.volume_available = false;
+
+        assert!(config.validate().unwrap_err().contains("REQUIRE_VOLUME"));
+    }
+
+    #[test]
+    fn embedded_config_accepts_required_available_volume() {
+        let mut config = base_config();
+        config.require_volume = true;
+        config.volume_available = true;
+
+        assert_eq!(config.validate(), Ok(()));
+    }
 }