Preserve whole-file source location in state-aware phase-config errors

This PR gives state-aware per-backend per-phase configuration parse errors
real whole-file line/column locations, matching base-config errors.

Details

* Retain the decoded request text on ParsedStateAwareRequest (new source_text
  field) and, at dispatch, deserialize the experimental.<backend>.<phase>
  sub-slice positionally with config_deserialize::from_str instead of from a
  serde_json::Value, so typed errors carry source coordinates.
* Translate the fragment-local serde location to whole-file coordinates via the
  sub-slice's byte offset; ConfigDeserializeError gains an optional location
  override consumed by Display (applied before secret redaction / control-char
  escaping so all existing guarantees hold), plus byte-offset<->line/column
  helpers and remap_error_to_source.
* Graceful fallback to the prior value-based path when the sub-slice cannot be
  located, so a would-be typed error is never turned into a navigation panic
  and there is no regression.

Tests

* New tests asserting the whole-file line/column for a typed phase-config error
  at two different global lines (line 5 and line 7), proving the location is
  computed, not hardcoded; a fallback test that the value-based path still emits
  the JSON-path prefix without source_text; unit tests for the
  byte-offset<->line/column helpers (round-trip + hand-computed cases) and the
  trailing-location rewrite.
* cargo fmt --all -- --check: passed.
* cargo test -p wxc_common: 500 passed; 0 failed.
* cargo clippy -p wxc_common --all-targets -- -D warnings: clean.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 041c1289-dedb-4acf-9949-516feb19fe1e

Author: Gudge

docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md

@@ -1095,8 +1095,10 @@ state-aware-only fields (`phase`, `sandboxId`, `experimental.<backend>.<phase>`)
 are extracted alongside the `ExecutionRequest` and bundled into a
 `ParsedStateAwareRequest` domain model — `{ request: ExecutionRequest, phase:
 Phase, containment: Option<ContainmentBackend>, sandbox_id: Option<String>,
-experimental_raw: Option<serde_json::Value> }` — that the dispatcher consumes
-(§9.3). The bundling does not modify `ExecutionRequest`'s shape. Domain models
+experimental_raw: Option<serde_json::Value>, source_text: Option<Box<str>> }` —
+that the dispatcher consumes (§9.3). `source_text` retains the decoded request
+text so per-backend per-phase config errors can be reported with whole-file
+source location (§9.3). The bundling does not modify `ExecutionRequest`'s shape. Domain models
 are exposed to the dispatch layer; the wire types are an implementation detail of
 the parser and schema generation.
 
@@ -1448,7 +1450,13 @@ prefix) or `malformed_id` (no prefix structure) per §8.
 `Result<Option<C>, MxcError>`: it navigates the wire `experimental.<backend_key>.<phase_name>`
 JSON value and deserialises it into `C` when present, returns `Ok(None)` when absent,
 and surfaces malformed JSON as `malformed_request`. The dispatcher passes
-`B::BACKEND_KEY` so each backend reads from its own slot.
+`B::BACKEND_KEY` so each backend reads from its own slot. Typed errors carry the
+complete `experimental.<backend>.<phase>.<field>` JSON path **and** whole-file
+source location (line/column), at parity with base-config errors: the phase-config
+sub-slice is deserialised positionally out of the retained request text and its
+fragment-local serde location is translated back to whole-file coordinates. If the
+sub-slice cannot be located, deserialisation falls back to the value-based path,
+which still reports the JSON path (without a source location).
 `sandbox_id_required()` enforces that non-provision phases carry a `sandboxId`,
 returning `&str` on success or `malformed_request` on absence. `validate_exec_common`
 is a free function in `validator.rs` that checks cross-backend per-phase invariants

src/core/mxc_engine/src/state_aware.rs

@@ -174,6 +174,7 @@ mod tests {
             sandbox_id: None,
             correlation_vector: None,
             experimental_raw: None,
+            source_text: None,
         };
 
         let error = run_state_aware(parsed, false).unwrap_err();

src/core/wxc/src/main.rs

@@ -1710,6 +1710,7 @@ mod tests {
             sandbox_id: Some("iso:wxc-1234".into()),
             correlation_vector: None,
             experimental_raw: None,
+            source_text: None,
         };
 
         let err = command_override_context_for_state_aware(&parsed, true).unwrap_err();

src/core/wxc_common/src/config_deserialize.rs

@@ -32,6 +32,11 @@ const SECRET_PATH_MARKERS: &[&str] = &[
 pub(crate) struct ConfigDeserializeError {
     path: Option<String>,
     source: serde_json::Error,
+    /// Whole-file `(line, column)` that overrides the location baked into
+    /// `source` when the error was produced from a sub-slice of a larger
+    /// request (e.g. a state-aware `experimental.<backend>.<phase>` fragment).
+    /// `None` leaves `source`'s own location untouched.
+    location_override: Option<(usize, usize)>,
 }
 
 impl ConfigDeserializeError {
@@ -41,9 +46,25 @@ impl ConfigDeserializeError {
         Self {
             path,
             source: error.into_inner(),
+            location_override: None,
         }
     }
 
+    /// Override the source location rendered by `Display` with whole-file
+    /// coordinates. Used when translating a fragment-local serde location back
+    /// to its position in the complete request text.
+    pub(crate) fn with_source_location(mut self, line: usize, column: usize) -> Self {
+        self.location_override = Some((line, column));
+        self
+    }
+
+    /// The `(line, column)` serde recorded for this error, or `None` when serde
+    /// could not attribute a position (it reports line 0 in that case).
+    pub(crate) fn source_line_column(&self) -> Option<(usize, usize)> {
+        let line = self.source.line();
+        (line > 0).then(|| (line, self.source.column()))
+    }
+
     /// Prefix a path produced while deserializing a JSON subtree with its path
     /// in the complete request.
     pub(crate) fn with_prefix(mut self, prefix: &str) -> Self {
@@ -77,6 +98,13 @@ impl fmt::Display for ConfigDeserializeError {
         } else {
             self.source.to_string()
         };
+        // Remap the source's baked-in `line/column` to whole-file coordinates
+        // before escaping so all downstream guarantees (control-char escaping,
+        // secret redaction, syntax-vs-data branch) still hold unchanged.
+        let source = match self.location_override {
+            Some((line, column)) => rewrite_trailing_location(&source, line, column),
+            None => source,
+        };
         let source = escape_control_characters(&source);
         match self.source.classify() {
             Category::Syntax | Category::Eof => {
@@ -106,6 +134,116 @@ fn redact_secret_value(source: &serde_json::Error) -> String {
     "invalid secret value".to_string()
 }
 
+/// Replace a trailing serde-style ` at line <N> column <M>` suffix in a rendered
+/// error message with the supplied whole-file `line`/`column`. serde_json emits
+/// this stable suffix on positioned errors; if it is absent (unpositioned
+/// message), the location is appended so the caller still gets coordinates.
+fn rewrite_trailing_location(rendered: &str, line: usize, column: usize) -> String {
+    let replacement = format!(" at line {line} column {column}");
+    if let Some(index) = rendered.rfind(" at line ") {
+        if is_location_suffix(&rendered[index..]) {
+            return format!("{}{}", &rendered[..index], replacement);
+        }
+    }
+    format!("{rendered}{replacement}")
+}
+
+/// True when `suffix` is exactly ` at line <digits> column <digits>` with no
+/// trailing text — serde_json's positioned-error suffix shape.
+fn is_location_suffix(suffix: &str) -> bool {
+    let Some(rest) = suffix.strip_prefix(" at line ") else {
+        return false;
+    };
+    let (line_digits, rest) = split_leading_digits(rest);
+    if line_digits.is_empty() {
+        return false;
+    }
+    let Some(rest) = rest.strip_prefix(" column ") else {
+        return false;
+    };
+    let (column_digits, rest) = split_leading_digits(rest);
+    !column_digits.is_empty() && rest.is_empty()
+}
+
+fn split_leading_digits(text: &str) -> (&str, &str) {
+    let end = text
+        .find(|character: char| !character.is_ascii_digit())
+        .unwrap_or(text.len());
+    text.split_at(end)
+}
+
+/// 1-based `(line, column)` (serde_json semantics) → byte offset within `text`.
+///
+/// Column arithmetic assumes ASCII configs (bytes == columns); the parser only
+/// ever hands us JSON, which is ASCII outside string literals, and offsets are
+/// only used to translate error positions. Returns `None` when the position is
+/// out of range so callers can fall back gracefully.
+fn byte_offset_of_line_col(text: &str, line: usize, column: usize) -> Option<usize> {
+    if line == 0 || column == 0 {
+        return None;
+    }
+    let bytes = text.as_bytes();
+    let mut current_line = 1usize;
+    let mut line_start = 0usize;
+    let mut index = 0usize;
+    while current_line < line && index < bytes.len() {
+        if bytes[index] == b'\n' {
+            current_line += 1;
+            line_start = index + 1;
+        }
+        index += 1;
+    }
+    if current_line < line {
+        return None;
+    }
+    let offset = line_start + (column - 1);
+    (offset <= text.len()).then_some(offset)
+}
+
+/// Byte offset within `text` → 1-based `(line, column)` (serde_json semantics).
+///
+/// Line counting is byte-exact; column arithmetic assumes ASCII (see
+/// [`byte_offset_of_line_col`]). Operates on bytes to avoid slicing panics on a
+/// non-char-boundary offset.
+fn line_col_of_byte_offset(text: &str, offset: usize) -> (usize, usize) {
+    let bytes = text.as_bytes();
+    let end = offset.min(bytes.len());
+    let mut line = 1usize;
+    let mut last_newline: Option<usize> = None;
+    for (index, byte) in bytes.iter().enumerate().take(end) {
+        if *byte == b'\n' {
+            line += 1;
+            last_newline = Some(index);
+        }
+    }
+    let column = match last_newline {
+        Some(index) => end - index,
+        None => end + 1,
+    };
+    (line, column)
+}
+
+/// Translate a `ConfigDeserializeError` produced by deserializing `fragment`
+/// (which begins at byte `fragment_offset` within `source_text`) so its
+/// rendered location reports whole-file coordinates instead of fragment-local
+/// ones. Any step that cannot be resolved returns `err` unchanged.
+pub(crate) fn remap_error_to_source(
+    err: ConfigDeserializeError,
+    fragment: &str,
+    fragment_offset: usize,
+    source_text: &str,
+) -> ConfigDeserializeError {
+    let Some((line, column)) = err.source_line_column() else {
+        return err;
+    };
+    let Some(local_offset) = byte_offset_of_line_col(fragment, line, column) else {
+        return err;
+    };
+    let global_offset = fragment_offset + local_offset;
+    let (global_line, global_column) = line_col_of_byte_offset(source_text, global_offset);
+    err.with_source_location(global_line, global_column)
+}
+
 fn escape_control_characters(value: &str) -> String {
     let mut escaped = String::with_capacity(value.len());
     for character in value.chars() {
@@ -187,7 +325,11 @@ where
     let value = deserialize_with_path(&mut deserializer)?;
     deserializer
         .end()
-        .map_err(|source| ConfigDeserializeError { path: None, source })?;
+        .map_err(|source| ConfigDeserializeError {
+            path: None,
+            source,
+            location_override: None,
+        })?;
     Ok(value)
 }
 
@@ -412,6 +554,7 @@ mod tests {
             let error = ConfigDeserializeError {
                 path: Some(path.to_string()),
                 source: serde_json::from_str::<Secret>(r#"{"wamToken": 123456789}"#).unwrap_err(),
+                location_override: None,
             };
 
             assert!(
@@ -426,6 +569,7 @@ mod tests {
         let error = ConfigDeserializeError {
             path: Some("monkey".to_string()),
             source: serde_json::from_str::<Secret>(r#"{"wamToken": 123456789}"#).unwrap_err(),
+            location_override: None,
         };
 
         assert!(!error.to_string().contains("invalid secret value"));
@@ -449,4 +593,93 @@ mod tests {
         let plain = "plain diagnostic text 123";
         assert_eq!(escape_diagnostic_text(plain), plain);
     }
+
+    #[test]
+    fn byte_offset_and_line_col_round_trip() {
+        let text = "line one\nline two\nline three\n";
+        // Walk every byte offset and confirm the offset -> (line,col) -> offset
+        // round-trip is stable.
+        for offset in 0..=text.len() {
+            let (line, column) = line_col_of_byte_offset(text, offset);
+            assert_eq!(
+                byte_offset_of_line_col(text, line, column),
+                Some(offset),
+                "round trip failed at offset {offset} -> ({line},{column})"
+            );
+        }
+    }
+
+    #[test]
+    fn line_col_of_byte_offset_hand_computed_cases() {
+        let text = "abc\ndefgh\nij";
+        // Offset 0 is line 1 column 1.
+        assert_eq!(line_col_of_byte_offset(text, 0), (1, 1));
+        // Offset 2 ('c') is line 1 column 3.
+        assert_eq!(line_col_of_byte_offset(text, 2), (1, 3));
+        // Offset 4 (start of "defgh") is line 2 column 1.
+        assert_eq!(line_col_of_byte_offset(text, 4), (2, 1));
+        // Offset 7 ('g') is line 2 column 4.
+        assert_eq!(line_col_of_byte_offset(text, 7), (2, 4));
+        // Offset 10 (start of "ij") is line 3 column 1.
+        assert_eq!(line_col_of_byte_offset(text, 10), (3, 1));
+    }
+
+    #[test]
+    fn byte_offset_of_line_col_hand_computed_and_out_of_range() {
+        let text = "abc\ndefgh\nij";
+        // Line 2 column 1 is the byte after the first newline.
+        assert_eq!(byte_offset_of_line_col(text, 2, 1), Some(4));
+        // Line 3 column 2 -> 'j'.
+        assert_eq!(byte_offset_of_line_col(text, 3, 2), Some(11));
+        // A line beyond the text has no offset.
+        assert_eq!(byte_offset_of_line_col(text, 9, 1), None);
+        // serde reports 0 for unknown positions; reject those.
+        assert_eq!(byte_offset_of_line_col(text, 0, 1), None);
+        assert_eq!(byte_offset_of_line_col(text, 1, 0), None);
+    }
+
+    #[test]
+    fn rewrite_trailing_location_replaces_existing_suffix() {
+        let rendered = "missing field `configuration_id` at line 2 column 5";
+        let rewritten = rewrite_trailing_location(rendered, 7, 11);
+        assert_eq!(
+            rewritten,
+            "missing field `configuration_id` at line 7 column 11"
+        );
+    }
+
+    #[test]
+    fn rewrite_trailing_location_appends_when_absent() {
+        let rendered = "some message without a position";
+        let rewritten = rewrite_trailing_location(rendered, 3, 4);
+        assert_eq!(
+            rewritten,
+            "some message without a position at line 3 column 4"
+        );
+    }
+
+    #[test]
+    fn remap_error_translates_fragment_local_location_to_whole_file() {
+        // A fragment that starts several lines into the whole file. The typed
+        // error inside it must be reported at its whole-file line/column.
+        let source_text = "line1\nline2\nline3\n{\n  \"count\": \"many\"\n}\n";
+        let fragment = "{\n  \"count\": \"many\"\n}";
+        let fragment_offset = source_text.find(fragment).unwrap();
+
+        let err = from_str::<Inner>(fragment).unwrap_err();
+        // Fragment-local location: line 2 of the fragment.
+        assert_eq!(err.source_line_column().map(|(l, _)| l), Some(2));
+
+        let remapped = remap_error_to_source(err, fragment, fragment_offset, source_text);
+        let message = remapped.to_string();
+        // The offending field sits on whole-file line 5.
+        assert!(
+            message.contains("line 5"),
+            "expected whole-file line 5, got: {message}"
+        );
+        assert!(
+            !message.contains("line 2"),
+            "still fragment-local: {message}"
+        );
+    }
 }

src/core/wxc_common/src/config_parser.rs

@@ -1261,6 +1261,10 @@ fn convert_wire_state_aware(
         sandbox_id,
         correlation_vector,
         experimental_raw,
+        // Retain the decoded request text so the dispatcher can deserialize each
+        // `experimental.<backend>.<phase>` sub-slice positionally and report
+        // typed errors with whole-file line/column (parity with base config).
+        source_text: Some(json.to_owned().into_boxed_str()),
     })
 }