feat(compiler): expose query operation descriptors

[mrkorchun]

Closes the first compiler/lint slice of #468.

Summary

• adds an optional operation descriptor to each successful query-lint result while keeping the existing top-level parameter catalog unchanged;
• exposes ordered result fields through a closed structured type shape (kind, optional item_kind, optional vector_dim, and nullable) rather than string spellings clients would need to parse;
• reports deterministic conservative reads and exact possible writes for node and edge facts, including nested not { ... }, mutation targets, edge-insert endpoints, and node-delete cascade edges;
• carries the typechecker-resolved node/edge namespace into the descriptor, including schemas where a node and edge share the same name;
• omits operation when parsing or typechecking fails.

The JSON change is additive. Existing lint fields, top-level parameter metadata, and query behavior are unchanged, so older consumers may ignore operation.

Scope

This PR intentionally stops at the compiler/lint boundary. Projection through GET /queries, OpenAPI, and the official TypeScript SDK remains follow-up work under #468.

Validation

• cargo fmt --all -- --check
• scripts/check-agents-md.sh
• cargo test -p omnigraph-compiler --locked — 314 passed
• cargo test -p omnigraph-cli --test cli_data --locked — 77 passed
• cargo clippy --workspace --all-targets --locked -- -D warnings -W clippy::dbg_macro
• cargo clippy --workspace --all-targets --locked --features omnigraph-engine/failpoints,omnigraph-cluster/failpoints -- -D warnings -W clippy::dbg_macro
• RUST_MIN_STACK=16777216 cargo test --workspace --locked --features omnigraph-engine/failpoints,omnigraph-cluster/failpoints

The larger stack is a local macOS test-harness accommodation for the existing large Blob branching fixture; the canonical feature-superset graph then passed in full.

Greptile Summary

Successful query lint results now expose a compiler-owned operation descriptor, while failed queries omit it.

• Describes ordered result fields using structured value kinds.
• Reports deterministic graph read/write facts for read queries and mutations.
• Preserves resolved node-versus-edge mutation namespaces and documents the JSON contract.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; both previously reported issues are fixed at the current head.

Important Files Changed

Filename	Overview
crates/omnigraph-compiler/src/query/descriptor.rs	Adds the shared operation-descriptor model and derives structured result fields plus deterministic graph access facts.
crates/omnigraph-compiler/src/query/lint.rs	Attaches descriptors only to successfully compiled per-query lint results.
crates/omnigraph-compiler/src/query/typecheck.rs	Retains the resolved node-or-edge namespace for each mutation target.
crates/omnigraph-compiler/src/query/lint_tests.rs	Covers result shapes, recursive reads, constrained edge inserts, node-delete cascades, deterministic facts, and failed-query omission.
docs/user/queries/index.md	Documents the operation JSON shape, ordering, naming, omission behavior, and read/write semantics.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Parsed QueryDecl] --> B[Typecheck]
  B -->|failure| C[Lint error without operation]
  B -->|CheckedQuery| D[Describe operation]
  D --> E[Infer ordered result schema]
  D --> F[Collect graph reads and writes]
  E --> G[QueryOperationDescriptor]
  F --> G
  G --> H[Successful lint JSON]

Loading

_{Reviews (4): Last reviewed commit: "fix(compiler): make operation descriptor..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Query language pipeline (parse → lint → typecheck → lower)
• Knowledge Base — Compiler Schema and Catalog