feat(MR-656): inline query strings in CLI and HTTP server

CLI:
- Add -e / --query-string <STRING> to omnigraph read and omnigraph change
- Exactly one of --query, --query-string, --alias is required (3-way XOR)
- Empty --query-string is rejected with a clear error

HTTP:
- New POST /query (read-only, clean field names: query/name/params/branch/snapshot)
- Mutations on /query are rejected with 400 -- use POST /change instead
- ChangeRequest fields polished: query (alias query_source), name (alias query_name)
- POST /read and POST /change remain byte-compatible for existing clients

Tests:
- cli.rs: -e happy-path on read/change, mutex error vs --query, empty -e rejected
- system_local.rs: inline -e read and -e change exercise the local flow
- system_remote.rs: inline -e read/change over HTTP plus direct /query 200/400
- server.rs: /query 200, /query 400 on mutation, /change legacy field alias
- openapi.rs: new /query path, QueryRequest schema, ChangeRequest field-name polish

Docs: cli.md (-e examples), cli-reference.md (read/change rows), server.md (/query)
Co-Authored-By: Ragnor Comerford <ragnor.comerford@gmail.com>

crates/omnigraph-server/src/api.rs

@@ -248,17 +248,49 @@ pub struct ReadRequest {
     pub snapshot: Option<String>,
 }
 
+/// Inline read-query request for `POST /query`.
+///
+/// Friendlier-named alternative to [`ReadRequest`] for ad-hoc reads and
+/// AI-agent integration. Mutations are rejected with 400 — use `POST
+/// /change` for write queries. Field names are deliberately short
+/// (`query`, `name`) to match the GQ keyword and the CLI `-e` flag.
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct QueryRequest {
+    /// GQ read-query source. May declare one or more named queries; pick one
+    /// with `name` when more than one is declared. Mutations
+    /// (`insert`/`update`/`delete`) get 400 — use `POST /change` instead.
+    #[schema(example = "query get_person($name: String) {\n    match {\n        $p: Person { name: $name }\n    }\n    return { $p.name, $p.age }\n}")]
+    pub query: String,
+    /// Name of the query to run when `query` declares multiple. Optional when
+    /// only one query is declared.
+    pub name: Option<String>,
+    /// JSON object whose keys match the query's declared parameters.
+    pub params: Option<Value>,
+    /// Branch to read from. Mutually exclusive with `snapshot`. Defaults to `main`.
+    pub branch: Option<String>,
+    /// Snapshot id to read from. Mutually exclusive with `branch`.
+    pub snapshot: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct ChangeRequest {
     /// GQ mutation source containing `insert`, `update`, or `delete` statements.
-    /// May declare multiple named mutations; pick one with `query_name`.
+    /// May declare multiple named mutations; pick one with `name`.
+    ///
+    /// Accepts the legacy field name `query_source` as a deserialization alias.
     #[schema(example = "query insert_person($name: String, $age: I32) {\n    insert Person { name: $name, age: $age }\n}")]
-    pub query_source: String,
-    /// Name of the mutation to run when `query_source` declares multiple.
-    pub query_name: Option<String>,
+    #[serde(alias = "query_source")]
+    pub query: String,
+    /// Name of the mutation to run when `query` declares multiple.
+    ///
+    /// Accepts the legacy field name `query_name` as a deserialization alias.
+    #[serde(default, alias = "query_name")]
+    pub name: Option<String>,
     /// JSON object whose keys match the mutation's declared parameters.
+    #[serde(default)]
     pub params: Option<Value>,
     /// Target branch. Defaults to `main`.
+    #[serde(default)]
     pub branch: Option<String>,
 }
 

crates/omnigraph-server/src/lib.rs

@@ -15,8 +15,8 @@ use api::{
     BranchCreateOutput, BranchCreateRequest, BranchDeleteOutput, BranchListOutput,
     BranchMergeOutput, BranchMergeRequest, ChangeOutput, ChangeRequest, CommitListOutput,
     CommitListQuery, ErrorCode, ErrorOutput, ExportRequest, HealthOutput, IngestOutput,
-    IngestRequest, ReadOutput, ReadRequest, SchemaApplyOutput, SchemaApplyRequest, SchemaOutput,
-    SnapshotQuery, ingest_output, schema_apply_output, snapshot_payload,
+    IngestRequest, QueryRequest, ReadOutput, ReadRequest, SchemaApplyOutput, SchemaApplyRequest,
+    SchemaOutput, SnapshotQuery, ingest_output, schema_apply_output, snapshot_payload,
 };
 use axum::body::{Body, Bytes};
 use axum::extract::DefaultBodyLimit;
@@ -74,6 +74,7 @@ fn hash_bearer_token(token: &str) -> BearerTokenHash {
         server_health,
         server_snapshot,
         server_read,
+        server_query,
         server_export,
         server_change,
         server_schema_apply,
@@ -631,6 +632,7 @@ pub fn build_app(state: AppState) -> Router {
         .route("/snapshot", get(server_snapshot))
         .route("/export", post(server_export))
         .route("/read", post(server_read))
+        .route("/query", post(server_query))
         .route("/change", post(server_change))
         .route("/schema", get(server_schema_get))
         .route("/schema/apply", post(server_schema_apply))
@@ -980,6 +982,85 @@ async fn server_read(
     Ok(Json(api::read_output(selected_name, &target, result)))
 }
 
+#[utoipa::path(
+    post,
+    path = "/query",
+    tag = "queries",
+    operation_id = "query",
+    request_body = QueryRequest,
+    responses(
+        (status = 200, description = "Query results", body = ReadOutput),
+        (status = 400, description = "Bad request - also returned when the query body contains mutations; use POST /change for write queries", body = ErrorOutput),
+        (status = 401, description = "Unauthorized", body = ErrorOutput),
+        (status = 403, description = "Forbidden", body = ErrorOutput),
+    ),
+    security(("bearer_token" = [])),
+)]
+/// Execute an inline read query (friendlier-named alternative to `POST /read`).
+///
+/// Designed for ad-hoc exploration and AI-agent tool-use: short field
+/// names (`query`, `name`) match the CLI `-e` flag and the GQ `query`
+/// keyword. Mutations (`insert`/`update`/`delete`) are rejected with 400
+/// -- use `POST /change` for write queries. Otherwise behaves
+/// identically to `POST /read`: same target semantics (branch xor
+/// snapshot), same Cedar action (Read), same response shape.
+async fn server_query(
+    State(state): State<AppState>,
+    actor: Option<Extension<AuthenticatedActor>>,
+    Json(request): Json<QueryRequest>,
+) -> std::result::Result<Json<ReadOutput>, ApiError> {
+    if request.branch.is_some() && request.snapshot.is_some() {
+        return Err(ApiError::bad_request(
+            "query request may specify branch or snapshot, not both",
+        ));
+    }
+
+    let target = read_target_from_request(request.branch, request.snapshot);
+    let policy_branch = match &target {
+        ReadTarget::Branch(branch) => Some(branch.clone()),
+        ReadTarget::Snapshot(_) if state.policy_engine().is_some() && actor.is_some() => {
+            let db = &state.engine;
+            db.resolved_branch_of(target.clone())
+                .await
+                .map(|branch| branch.or_else(|| Some("main".to_string())))
+                .map_err(ApiError::from_omni)?
+        }
+        ReadTarget::Snapshot(_) => None,
+    };
+    authorize_request(
+        &state,
+        actor.as_ref().map(|Extension(actor)| actor),
+        PolicyRequest {
+            actor_id: actor
+                .as_ref()
+                .map(|Extension(actor)| actor.as_str().to_string())
+                .unwrap_or_default(),
+            action: PolicyAction::Read,
+            branch: policy_branch,
+            target_branch: None,
+        },
+    )?;
+    let query_decl = select_named_query_decl(&request.query, request.name.as_deref())
+        .map_err(|err| ApiError::bad_request(err.to_string()))?;
+    if !query_decl.mutations.is_empty() {
+        return Err(ApiError::bad_request(format!(
+            "query '{}' contains mutations (insert/update/delete); use POST /change for write queries",
+            query_decl.name
+        )));
+    }
+    let selected_name = query_decl.name.clone();
+    let params = query_params_from_json(&query_decl.params, request.params.as_ref())
+        .map_err(|err| ApiError::bad_request(err.to_string()))?;
+
+    let result = {
+        let db = &state.engine;
+        db.query(target.clone(), &request.query, &selected_name, &params)
+            .await
+            .map_err(ApiError::from_omni)?
+    };
+    Ok(Json(api::read_output(selected_name, &target, result)))
+}
+
 #[utoipa::path(
     post,
     path = "/export",
@@ -1092,7 +1173,7 @@ async fn server_change(
     // estimated bytes per actor. Cedar runs FIRST so denied requests
     // don't consume admission slots. Estimate uses the request body
     // size as a coarse proxy; engine memory pressure can run higher.
-    let est_bytes = request.query_source.len() as u64
+    let est_bytes = request.query.len() as u64
         + request
             .params
             .as_ref()
@@ -1103,7 +1184,7 @@ async fn server_change(
         .try_admit(&actor_arc, est_bytes)
         .map_err(ApiError::from_workload_reject)?;
     let (selected_name, query_params) =
-        select_named_query(&request.query_source, request.query_name.as_deref())
+        select_named_query(&request.query, request.name.as_deref())
             .map_err(|err| ApiError::bad_request(err.to_string()))?;
     let params = query_params_from_json(&query_params, request.params.as_ref())
         .map_err(|err| ApiError::bad_request(err.to_string()))?;
@@ -1112,7 +1193,7 @@ async fn server_change(
         let db = &state.engine;
         db.mutate_as(
             &branch,
-            &request.query_source,
+            &request.query,
             &selected_name,
             &params,
             actor_id,
@@ -1658,10 +1739,10 @@ fn read_target_from_request(branch: Option<String>, snapshot: Option<String>) ->
     }
 }
 
-fn select_named_query(
+fn select_named_query_decl(
     query_source: &str,
     requested_name: Option<&str>,
-) -> Result<(String, Vec<omnigraph_compiler::query::ast::Param>)> {
+) -> Result<omnigraph_compiler::query::ast::QueryDecl> {
     let parsed = parse_query(query_source)?;
     let query = if let Some(name) = requested_name {
         parsed
@@ -1674,7 +1755,14 @@ fn select_named_query(
     } else {
         bail!("query file contains multiple queries; pass --name");
     };
+    Ok(query)
+}
 
+fn select_named_query(
+    query_source: &str,
+    requested_name: Option<&str>,
+) -> Result<(String, Vec<omnigraph_compiler::query::ast::Param>)> {
+    let query = select_named_query_decl(query_source, requested_name)?;
     Ok((query.name, query.params))
 }