[M3] mxaccess-galaxy: GalaxyTagMetadata + parser + Resolver trait + SQL

Lands M3 stream A — the pure-Rust foundation of the Galaxy resolver:
the data type, the tag-reference parser, the async trait, and the
canonical SQL strings. Unblocks F13 (NmxClient::write_* wrappers depend
on GalaxyTagMetadata) without pulling in tiberius yet.

New
- metadata.rs (~195 LoC, 7 tests) — GalaxyTagMetadata record (port of
  cs:6-73). Includes is_buffer_property + to_reference_handle(galaxy_id)
  bridging into mxaccess-codec::MxReferenceHandle::from_names.
- parser.rs (~330 LoC, 12 tests) — ParsedTagReference parser. Handles
  Object.Attribute (1 candidate), Object.Primitive.Attribute (2
  candidates: primitive-attr first, dotted-attr second per cs:181-185),
  and the case-insensitive .property(buffer) suffix. Pure-Rust, no I/O.
- resolver.rs (~200 LoC, 5 tests including a tokio-driven InMemoryResolver
  proving the trait is implementable without SQL) — async Resolver trait
  + ResolverError. Default browse returns Backend("not implemented") so
  read-only backends don't need to override it.
- sql.rs (~280 LoC, 5 smoke tests) — RESOLVE_SQL + BROWSE_SQL constants
  ported byte-for-byte from cs:208-432. Available publicly so any
  backend (the planned tiberius impl, a wwtools/grdb snapshot replay,
  etc.) can grab the canonical query.

Cargo.toml: added mxaccess-codec (path), async-trait, thiserror;
tokio added as dev-dependency for the resolver-trait async tests.

Deliberately deferred to a later iteration:
- The tiberius-backed Resolver impl behind the galaxy-resolver feature.
- ToValueKind / TryGetValueKind / ProjectWriteValue helpers on
  GalaxyTagMetadata (cs:41-72) — these need a MxDataType -> MxValueKind
  lookup that the codec doesn't currently expose; landing them with
  F13's write-helper iteration keeps the iteration coherent.

Test count delta: 397 -> 427 (+30). All four DoD gates green.
Open followups touched: F13 prerequisite (GalaxyTagMetadata) now in
place; F13 itself stays open until the write helpers wire it up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

rust/crates/mxaccess-galaxy/src/resolver.rs

@@ -0,0 +1,197 @@
+//! `Resolver` async trait — pluggable backend for tag-name lookup.
+//!
+//! The .NET reference's `GalaxyRepositoryTagResolver` is a single concrete
+//! class with a SQL backend. The Rust port splits the surface into a trait
+//! plus one provided implementation (`tiberius`-backed, gated by the
+//! `galaxy-resolver` Cargo feature) so consumers can plug in any other
+//! backing — an in-memory cache for tests, a JSON snapshot from
+//! `wwtools/grdb/`, a future REST client, etc.
+//!
+//! Both [`Resolver::resolve`] and [`Resolver::browse`] mirror the .NET
+//! `ResolveAsync` and `BrowseAsync` signatures (`GalaxyRepositoryTagResolver.cs:88,117`).
+
+use crate::metadata::GalaxyTagMetadata;
+use crate::parser::ParseError;
+use async_trait::async_trait;
+use thiserror::Error;
+
+/// Errors raised by [`Resolver`] implementations. Mirrors the
+/// `InvalidOperationException` raised by .NET when a tag is not found
+/// (`GalaxyRepositoryTagResolver.cs:114`) plus parser failures from
+/// [`crate::parser::ParsedTagReference::parse_candidates`].
+#[derive(Debug, Error)]
+#[non_exhaustive]
+pub enum ResolverError {
+    /// The tag-reference string itself failed to parse.
+    #[error("invalid tag reference: {0}")]
+    InvalidTagReference(#[from] ParseError),
+
+    /// No metadata row matched any of the parsed candidates. Mirrors
+    /// `cs:114`.
+    #[error(
+        "Galaxy tag reference '{tag_reference}' was not found in the deployed repository metadata"
+    )]
+    NotFound { tag_reference: String },
+
+    /// Backend-specific failure (SQL connect / query error, transport
+    /// error, etc.). Carries an opaque message so backends don't have to
+    /// expose their concrete error types in the trait.
+    #[error("Galaxy resolver backend error: {message}")]
+    Backend { message: String },
+}
+
+/// Pluggable async tag-name → metadata resolver.
+///
+/// Implementations should be thread-safe (`Send + Sync`) so the Rust
+/// `NmxClient` can hold one in an `Arc<dyn Resolver>` shared across
+/// multiple write/advise calls.
+#[async_trait]
+pub trait Resolver: Send + Sync {
+    /// Resolve a single tag reference (`Object.Attribute`,
+    /// `Object.Primitive.Attribute`, optionally `.property(buffer)`-
+    /// suffixed) to its metadata. Mirrors `ResolveAsync`
+    /// (`GalaxyRepositoryTagResolver.cs:88-115`).
+    ///
+    /// # Errors
+    /// [`ResolverError::InvalidTagReference`], [`ResolverError::NotFound`],
+    /// or [`ResolverError::Backend`].
+    async fn resolve(&self, tag_reference: &str) -> Result<GalaxyTagMetadata, ResolverError>;
+
+    /// Browse multiple matching attributes. The default implementation
+    /// returns [`ResolverError::Backend`] with `"browse not implemented"`
+    /// — backends that support browsing override this. Mirrors
+    /// `BrowseAsync` (`cs:117-147`).
+    ///
+    /// `object_tag_like` and `attribute_like` use SQL `LIKE` semantics
+    /// (`%` for any-sequence, `_` for any-single-char).
+    ///
+    /// # Errors
+    /// As for [`Self::resolve`].
+    async fn browse(
+        &self,
+        object_tag_like: &str,
+        attribute_like: &str,
+        max_rows: usize,
+    ) -> Result<Vec<GalaxyTagMetadata>, ResolverError> {
+        let _ = (object_tag_like, attribute_like, max_rows);
+        Err(ResolverError::Backend {
+            message: "browse not implemented for this resolver".to_string(),
+        })
+    }
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::unwrap_used,
+    clippy::expect_used,
+    clippy::indexing_slicing,
+    clippy::panic
+)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+    use std::sync::Mutex;
+
+    /// Tiny in-memory resolver for tests. Demonstrates that the trait is
+    /// implementable without any SQL machinery, validating the
+    /// "pluggable backend" design.
+    struct InMemoryResolver {
+        rows: HashMap<String, GalaxyTagMetadata>,
+        browse_calls: Mutex<Vec<(String, String, usize)>>,
+    }
+
+    impl InMemoryResolver {
+        fn new() -> Self {
+            let mut rows = HashMap::new();
+            rows.insert(
+                "TestObject.TestAttr".to_string(),
+                GalaxyTagMetadata {
+                    object_tag_name: "TestObject".to_string(),
+                    attribute_name: "TestAttr".to_string(),
+                    primitive_name: None,
+                    platform_id: 1,
+                    engine_id: 2,
+                    object_id: 3,
+                    primitive_id: 0,
+                    attribute_id: 7,
+                    property_id: 10,
+                    mx_data_type: 4,
+                    is_array: false,
+                    security_classification: 0,
+                    attribute_source: "dynamic".to_string(),
+                },
+            );
+            Self {
+                rows,
+                browse_calls: Mutex::new(Vec::new()),
+            }
+        }
+    }
+
+    #[async_trait]
+    impl Resolver for InMemoryResolver {
+        async fn resolve(&self, tag_reference: &str) -> Result<GalaxyTagMetadata, ResolverError> {
+            self.rows
+                .get(tag_reference)
+                .cloned()
+                .ok_or_else(|| ResolverError::NotFound {
+                    tag_reference: tag_reference.to_string(),
+                })
+        }
+
+        async fn browse(
+            &self,
+            object_tag_like: &str,
+            attribute_like: &str,
+            max_rows: usize,
+        ) -> Result<Vec<GalaxyTagMetadata>, ResolverError> {
+            self.browse_calls.lock().unwrap().push((
+                object_tag_like.to_string(),
+                attribute_like.to_string(),
+                max_rows,
+            ));
+            Ok(self.rows.values().take(max_rows).cloned().collect())
+        }
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn in_memory_resolver_round_trip() {
+        let r = InMemoryResolver::new();
+        let m = r.resolve("TestObject.TestAttr").await.unwrap();
+        assert_eq!(m.object_tag_name, "TestObject");
+        assert_eq!(m.attribute_name, "TestAttr");
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn in_memory_resolver_not_found() {
+        let r = InMemoryResolver::new();
+        let err = r.resolve("DoesNotExist.X").await.unwrap_err();
+        assert!(matches!(err, ResolverError::NotFound { .. }));
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn default_browse_returns_backend_error() {
+        // Concrete impl that doesn't override browse picks up the default.
+        struct NoBrowse;
+        #[async_trait]
+        impl Resolver for NoBrowse {
+            async fn resolve(&self, _: &str) -> Result<GalaxyTagMetadata, ResolverError> {
+                unimplemented!()
+            }
+        }
+        let err = NoBrowse.browse("%", "%", 10).await.unwrap_err();
+        match err {
+            ResolverError::Backend { message } => {
+                assert!(message.contains("browse not implemented"));
+            }
+            other => panic!("expected Backend, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn parse_error_converts_into_resolver_error() {
+        // ResolverError::from(ParseError::Empty) via #[from].
+        let e: ResolverError = ParseError::Empty.into();
+        assert!(matches!(e, ResolverError::InvalidTagReference(_)));
+    }
+}