feat(rw-02,rw-03): typed Railway queries + mutations + service CLI (openai#3 openai#4 openai#5)

- AuthMode enum: auto-detect UUID-shaped Project-Access-Token
- queries: project_view, recent_deployments, service_variables, latest_deploy_id
- mutations: service_create, service_instance_set_image,
  variable_upsert, service_redeploy, service_delete
- bin/tri-railway: 'service list', 'service deploy', 'service redeploy',
  'service delete' verbs (R7 audit triplet appended on deploy)
- Live-tested against Railway IGLA project (verified service list +
  redeploy on seed-43 SUCCESS digest e53ade00)
- Fixed clippy items_after_test_module + needless_lifetimes
- 16 unit tests still green; build green

Closes openai#3
Closes openai#4
Closes openai#5

Refs: L-T5 (trainer-igla-sot), Gate-2 deadline 2026-04-30T23:59Z

Agent: GENERAL

Author: ghashtag-agent

bin/tri-railway/src/main.rs

@@ -17,9 +17,15 @@ use clap::{Parser, Subcommand};
 use std::path::PathBuf;
 
 use trios_railway_audit::migrations;
-use trios_railway_core::{ProjectId, RailwayHash, ServiceId};
+use trios_railway_core::{
+    mutations as M, queries as Q, Client, EnvironmentId, ProjectId, RailwayHash, ServiceId,
+};
 use trios_railway_experience::{append_line, ExperienceLine};
 
+const IGLA_PROJECT_ID: &str = "e4fe33bb-3b09-4842-9782-7d2dea1abc9b";
+const IGLA_PROD_ENV_ID: &str = "54e293b9-00a9-4102-814d-db151636d96e";
+const DEFAULT_TRAINER_IMAGE: &str = "ghcr.io/ghashtag/trios-trainer-igla:latest";
+
 #[derive(Parser, Debug)]
 #[command(
     name = "tri-railway",
@@ -53,6 +59,66 @@ enum Cmd {
         #[command(subcommand)]
         sub: ExperienceCmd,
     },
+
+    /// Service operations against Railway (RW-02 + RW-03).
+    ///
+    /// Requires `RAILWAY_TOKEN` in the environment. UUID-shaped tokens
+    /// are auto-detected as project-access tokens.
+    Service {
+        #[command(subcommand)]
+        sub: ServiceCmd,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+enum ServiceCmd {
+    /// Print all services in the configured project.
+    List {
+        #[arg(long, env = "TRIOS_RAILWAY_PROJECT", default_value = IGLA_PROJECT_ID)]
+        project: String,
+    },
+    /// Create a new image-backed service named `--name` with `--image`,
+    /// upsert the variables, and trigger one redeploy. R7 audit triplet
+    /// is appended to the local experience log.
+    Deploy {
+        #[arg(long, env = "TRIOS_RAILWAY_PROJECT", default_value = IGLA_PROJECT_ID)]
+        project: String,
+        #[arg(long, env = "TRIOS_RAILWAY_ENV", default_value = IGLA_PROD_ENV_ID)]
+        environment: String,
+        /// Service name (e.g. `trios-train-seed-43`).
+        #[arg(long)]
+        name: String,
+        /// Docker image; defaults to the IGLA trainer image.
+        #[arg(long, default_value = DEFAULT_TRAINER_IMAGE)]
+        image: String,
+        /// `KEY=VALUE` env pairs to upsert. Repeatable.
+        #[arg(long = "var", value_name = "KEY=VALUE")]
+        vars: Vec<String>,
+        /// Reuse this existing service id instead of creating a new one.
+        #[arg(long)]
+        existing: Option<String>,
+        /// If set, only print what would happen.
+        #[arg(long)]
+        dry_run: bool,
+        /// Repo root for the experience log.
+        #[arg(long, default_value = ".")]
+        root: PathBuf,
+    },
+    /// Trigger a redeploy of an existing service.
+    Redeploy {
+        #[arg(long, env = "TRIOS_RAILWAY_ENV", default_value = IGLA_PROD_ENV_ID)]
+        environment: String,
+        #[arg(long)]
+        service: String,
+    },
+    /// Permanently delete a service.
+    Delete {
+        #[arg(long)]
+        service: String,
+        /// Confirm the destruction with `--yes`.
+        #[arg(long)]
+        yes: bool,
+    },
 }
 
 #[derive(Subcommand, Debug)]
@@ -129,6 +195,7 @@ async fn main() -> Result<()> {
                 println!("{stmt};");
             }
         }
+        Cmd::Service { sub } => run_service(sub).await?,
         Cmd::Experience { sub } => match sub {
             ExperienceCmd::Append {
                 root,
@@ -157,3 +224,111 @@ async fn main() -> Result<()> {
 
     Ok(())
 }
+
+fn parse_var(s: &str) -> Result<(String, String)> {
+    let (k, v) = s
+        .split_once('=')
+        .ok_or_else(|| anyhow::anyhow!("variable `{s}` is not in KEY=VALUE form"))?;
+    if k.is_empty() {
+        anyhow::bail!("empty variable name in `{s}`");
+    }
+    Ok((k.to_string(), v.to_string()))
+}
+
+async fn run_service(cmd: ServiceCmd) -> Result<()> {
+    let client =
+        Client::from_env().map_err(|e| anyhow::anyhow!("RAILWAY_TOKEN not set or invalid: {e}"))?;
+    let token_fp = client.token_fingerprint();
+
+    match cmd {
+        ServiceCmd::List { project } => {
+            let pid = ProjectId::from(project);
+            let pv = Q::project_view(&client, &pid).await?;
+            println!("project {} ({})", pv.name, pv.id);
+            for s in pv.services() {
+                println!("  {}  {}  {}", s.id, s.name, s.created_at);
+            }
+        }
+        ServiceCmd::Deploy {
+            project,
+            environment,
+            name,
+            image,
+            vars,
+            existing,
+            dry_run,
+            root,
+        } => {
+            let pid = ProjectId::from(project);
+            let eid = EnvironmentId::from(environment);
+            let mut parsed = Vec::with_capacity(vars.len());
+            for v in &vars {
+                parsed.push(parse_var(v)?);
+            }
+
+            if dry_run {
+                println!("DRY RUN: would deploy {name} from {image}");
+                println!("  project   = {}", pid.as_str());
+                println!("  env       = {}", eid.as_str());
+                if let Some(eid) = &existing {
+                    println!("  reuse svc = {eid}");
+                }
+                for (k, v) in &parsed {
+                    println!("  var       = {k}={v}");
+                }
+                return Ok(());
+            }
+
+            let service_id: ServiceId = if let Some(eid) = existing {
+                ServiceId::from(eid)
+            } else {
+                let created = M::service_create(&client, &pid, &name).await?;
+                println!("created service {} ({})", created.name, created.id);
+                ServiceId::from(created.id)
+            };
+
+            M::service_instance_set_image(&client, &service_id, &eid, &image).await?;
+            println!("set image: {image}");
+
+            for (k, v) in &parsed {
+                M::variable_upsert(&client, &pid, &eid, &service_id, k, v).await?;
+                println!("  var: {k}=<{}>", v.len());
+            }
+
+            let deploy_id = M::service_redeploy(&client, &service_id, &eid).await?;
+            println!("redeploy triggered: {deploy_id}");
+
+            // R7 triplet to local experience log.
+            let hash = RailwayHash::seal("deploy", &pid, Some(&service_id), &token_fp);
+            let line = ExperienceLine::from_hash(
+                "GENERAL",
+                "RailRangerOne",
+                "#5",
+                &format!("deploy {name} image={image}"),
+                "OK",
+                "PUSH",
+                &hash,
+            )?;
+            let path = append_line(&root.join(".trinity"), &line).await?;
+            println!("experience: {}", path.display());
+        }
+        ServiceCmd::Redeploy {
+            environment,
+            service,
+        } => {
+            let eid = EnvironmentId::from(environment);
+            let sid = ServiceId::from(service);
+            let deploy_id = M::service_redeploy(&client, &sid, &eid).await?;
+            println!("redeploy triggered: {deploy_id}");
+        }
+        ServiceCmd::Delete { service, yes } => {
+            if !yes {
+                anyhow::bail!("refusing to delete service `{service}` without --yes");
+            }
+            let sid = ServiceId::from(service);
+            M::service_delete(&client, &sid).await?;
+            println!("deleted: {sid}");
+        }
+    }
+    Ok(())
+}

crates/trios-railway-core/src/lib.rs

@@ -11,8 +11,10 @@
 
 pub mod hash;
 pub mod ids;
+pub mod mutations;
+pub mod queries;
 pub mod transport;
 
 pub use hash::RailwayHash;
 pub use ids::{DeployId, EnvironmentId, ProjectId, ServiceId};
-pub use transport::{Client, ClientError};
+pub use transport::{AuthMode, Client, ClientError};

crates/trios-railway-core/src/mutations.rs

@@ -0,0 +1,165 @@
+//! RW-03: typed mutations against the Railway GraphQL API.
+//!
+//! Mutations supported:
+//! - `serviceCreate` (image-based, project-scoped)
+//! - `variableUpsert` (one variable at a time, scoped to project + env + service)
+//! - `serviceInstanceDeployV2` (trigger a redeploy on the latest source)
+//! - `serviceInstanceUpdate` (set source.image so the next deploy pulls a new image)
+//! - `serviceDelete`
+//!
+//! All mutations log a `R7` triplet via `RailwayHash::seal` at the call site
+//! (callers must do that — this module returns plain ids).
+
+use serde::Deserialize;
+use serde_json::json;
+
+use crate::ids::{DeployId, EnvironmentId, ProjectId, ServiceId};
+use crate::transport::{Client, ClientError};
+
+pub const M_SERVICE_CREATE: &str = "mutation M($input: ServiceCreateInput!) {
+  serviceCreate(input: $input) { id name projectId }
+}";
+
+pub const M_VARIABLE_UPSERT: &str = "mutation M($input: VariableUpsertInput!) {
+  variableUpsert(input: $input)
+}";
+
+pub const M_DEPLOY_REDEPLOY: &str = "mutation M($serviceId: String!, $environmentId: String!) {
+  serviceInstanceRedeploy(serviceId: $serviceId, environmentId: $environmentId)
+}";
+
+pub const M_SERVICE_INSTANCE_UPDATE: &str =
+    "mutation M($serviceId: String!, $environmentId: String!, $input: ServiceInstanceUpdateInput!) {
+  serviceInstanceUpdate(serviceId: $serviceId, environmentId: $environmentId, input: $input)
+}";
+
+pub const M_SERVICE_DELETE: &str = "mutation M($id: String!) {
+  serviceDelete(id: $id)
+}";
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct CreatedService {
+    pub id: String,
+    pub name: String,
+    #[serde(rename = "projectId")]
+    pub project_id: String,
+}
+
+/// Create a new service in a project. The image is set on the service
+/// instance via a follow-up `serviceInstanceUpdate` call (Railway splits
+/// service vs service-instance config).
+pub async fn service_create(
+    client: &Client,
+    project: &ProjectId,
+    name: &str,
+) -> Result<CreatedService, ClientError> {
+    #[derive(Deserialize)]
+    struct R {
+        #[serde(rename = "serviceCreate")]
+        service_create: CreatedService,
+    }
+    let vars = json!({
+        "input": {
+            "projectId": project.as_str(),
+            "name": name,
+        }
+    });
+    let r: R = client.query(M_SERVICE_CREATE, Some(vars)).await?;
+    Ok(r.service_create)
+}
+
+/// Pin the image source on a service instance. The next redeploy will use it.
+pub async fn service_instance_set_image(
+    client: &Client,
+    service: &ServiceId,
+    env: &EnvironmentId,
+    image: &str,
+) -> Result<(), ClientError> {
+    let vars = json!({
+        "serviceId": service.as_str(),
+        "environmentId": env.as_str(),
+        "input": {
+            "source": { "image": image }
+        }
+    });
+    let _: serde_json::Value = client.query(M_SERVICE_INSTANCE_UPDATE, Some(vars)).await?;
+    Ok(())
+}
+
+/// Upsert a single environment variable for a service.
+pub async fn variable_upsert(
+    client: &Client,
+    project: &ProjectId,
+    env: &EnvironmentId,
+    service: &ServiceId,
+    name: &str,
+    value: &str,
+) -> Result<(), ClientError> {
+    let vars = json!({
+        "input": {
+            "projectId": project.as_str(),
+            "environmentId": env.as_str(),
+            "serviceId": service.as_str(),
+            "name": name,
+            "value": value,
+        }
+    });
+    let _: serde_json::Value = client.query(M_VARIABLE_UPSERT, Some(vars)).await?;
+    Ok(())
+}
+
+/// Redeploy a service in an environment using the most recent source.
+/// Returns the new deployment id.
+pub async fn service_redeploy(
+    client: &Client,
+    service: &ServiceId,
+    env: &EnvironmentId,
+) -> Result<DeployId, ClientError> {
+    #[derive(Deserialize)]
+    struct R {
+        #[serde(rename = "serviceInstanceRedeploy")]
+        service_instance_redeploy: serde_json::Value,
+    }
+    let vars = json!({
+        "serviceId": service.as_str(),
+        "environmentId": env.as_str(),
+    });
+    let r: R = client.query(M_DEPLOY_REDEPLOY, Some(vars)).await?;
+    let id = match r.service_instance_redeploy {
+        serde_json::Value::String(s) => s,
+        v => v.to_string(),
+    };
+    Ok(DeployId::new(id))
+}
+
+/// Permanently delete a service (and all its deployments).
+pub async fn service_delete(client: &Client, service: &ServiceId) -> Result<(), ClientError> {
+    let vars = json!({ "id": service.as_str() });
+    let _: serde_json::Value = client.query(M_SERVICE_DELETE, Some(vars)).await?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn mutation_strings_present() {
+        for m in [
+            M_SERVICE_CREATE,
+            M_VARIABLE_UPSERT,
+            M_DEPLOY_REDEPLOY,
+            M_SERVICE_INSTANCE_UPDATE,
+            M_SERVICE_DELETE,
+        ] {
+            assert!(m.contains("mutation M("));
+        }
+    }
+
+    #[test]
+    fn created_service_parses() {
+        let raw = serde_json::json!({"id":"s1","name":"trios-train-seed-43","projectId":"p"});
+        let cs: CreatedService = serde_json::from_value(raw).unwrap();
+        assert_eq!(cs.name, "trios-train-seed-43");
+    }
+}