Add actionable configuration parse errors

This PR adds actionable configuration parse errors: the parser reports
malformed JSON separately from typed policy-shape errors and includes the
full policy path plus whole-file source location in every diagnostic,
without leaking secrets or letting untrusted text corrupt diagnostics or
the state-aware stdout response envelope.

Details

* New config_deserialize module: a path-aware deserialize layer that
  distinguishes JSON syntax errors from typed policy errors, attaching the
  full JSON path and whole-file line/column, escaping control and invisible
  formatting characters (incl. U+2028/U+2029 and bidi overrides), and
  redacting secret-bearing values. Format-character detection uses the
  unicode-general-category crate (Format | LineSeparator | ParagraphSeparator)
  rather than a hand-maintained codepoint table, so the Cf/Zl/Zp set tracks
  the crate's Unicode tables.
* State-aware per-backend per-phase configs deserialize positionally from
  the retained request text, so typed errors carry whole-file coordinates
  matching base-config errors; navigation uses owned-key maps so escaped
  sibling keys never silently drop the location, with graceful fallback to
  the value-based path.
* Request loading borrows RawValue to discriminate one-shot vs state-aware
  without building a full untyped AST, masking the experimental subtree to
  preserve base-config source locations.
* Diagnostic routing keeps stdout reserved for the state-aware envelope and
  script output; parse and dispatch errors go to auxiliary sinks (log file /
  diagnostic pipe) only and are emitted exactly once. Filesystem-path and
  schema-version diagnostics escape untrusted text via the shared
  escape_diagnostic_text helper.
* Exec dispatch drops the parsed request (and its retained source text)
  before the blocking child run and stdio relay.
* Docs updated: versioning.md, the state-aware API doc, and the
  copilot-instructions config-flow description.

Tests

* Added parser coverage: syntax-vs-typed classification, whole-file
  line/column (computed, not hardcoded), escaped-sibling-key location
  preservation, exact column, CRLF line stability, positional secret
  redaction, source-present locator fallback, malformed-telemetry single
  auxiliary emission with an empty primary buffer, a pinned serde_json
  positioned-error display-suffix contract, and format-character escaping
  (U+202E/U+200B/U+2028/U+2029) that also pins the crate-based check.
* cargo fmt --all -- --check: passed.
* cargo clippy -p wxc_common -p mxc_engine -p wxc --all-targets -- -D warnings: clean.
* cargo test -p wxc_common -p wxc: 514 + 26 passed.
* node scripts/versioning/check-schema-codegen.js,
  check-sdk-types-codegen.js, check-schema-versions.js: passed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4cc05a95-546f-4acb-913a-b946127fa01f

Author: Gudge

.github/copilot-instructions.md

@@ -120,7 +120,7 @@ The Rust workspace (`src/`) implements multiple sandboxing backends behind the `
 
 ### Config flow
 
-1. User provides JSON config (file or base64) → `config_parser.rs` deserializes into the typed wire model (`wxc_common::wire`) → validates and maps to `ExecutionRequest` (the internal execution model in `models.rs`)
+1. User provides JSON config (file or base64) → `config_deserialize.rs` performs path-aware typed deserialization into the wire model (`wxc_common::wire`) → `config_parser.rs` validates and maps it to `ExecutionRequest` (the internal execution model in `models.rs`)
 2. `ExecutionRequest` includes the containment backend selection, process config, filesystem/network policies, and optional experimental features
 3. The appropriate `ScriptRunner` implementation executes the process and returns `ScriptResponse`
 
@@ -214,7 +214,7 @@ The workspace is organized into six top-level directories under `src/`:
 
 ### Config parser pattern
 
-The parser deserializes JSON directly into the typed wire model (`wxc_common::wire`), the single source of truth for the config shape (it also generates the JSON schema). `config_parser.rs` then maps the wire types to the validated domain structs in `models.rs`. The stable surface uses `deny_unknown_fields` (closed); the `experimental` block is permissive.
+The parser deserializes JSON directly into the typed wire model (`wxc_common::wire`), the single source of truth for the config shape (it also generates the JSON schema). All typed config deserialization goes through `config_deserialize.rs`, which distinguishes syntax errors from typed policy errors and adds the complete JSON path plus source line/column when available; state-aware backend errors are prefixed with their full `experimental.<backend>.<phase>` location. `config_parser.rs` then maps the wire types to the validated domain structs in `models.rs`. The stable surface uses `deny_unknown_fields` (closed); the `experimental` block is permissive.
 
 ### TypeScript conventions
 

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

@@ -722,6 +722,24 @@ state-aware mode so `stdout` remains parseable without sentinels. (One-shot disp
 keeps its existing `stdout` logger behaviour — the stricter routing applies to
 state-aware only.)
 
+Configuration parse-phase failures that occur **after** the request is
+discriminated as state-aware (i.e. the `phase` field was recognized) follow the
+state-aware contract: the typed `{error}` envelope is the only primary output,
+while the human-readable actionable parse diagnostic is written only to
+configured auxiliary sinks (`--log-file` and the Windows diagnostic console). It
+is not duplicated to the logger's primary console/buffer output, so such a parse
+failure does not add stderr noise even with `--debug`. Dispatch-time failures,
+including typed per-backend configuration errors, use the same auxiliary-only
+diagnostic routing before the executor emits their typed `{error}` envelope.
+
+Failures that occur **before** discrimination is possible — malformed base64,
+non-UTF-8 bytes, or JSON so malformed that the `phase` field cannot be read —
+cannot be attributed to the state-aware path, so they retain the legacy
+behavior: the diagnostic is written to the primary output (stderr) and **no**
+`{error}` envelope is emitted. Callers that require an envelope even for
+unparseable input should validate that the payload is well-formed JSON before
+invoking `wxc-exec`.
+
 For exec specifically, MXC diagnostic output mixes with the script's own stderr when
 `--debug` is passed. This is a small amount of pre- and post-dispatch noise; consumers
 wanting clean separation should use `--log-file <path>` instead, which routes diagnostic
@@ -1029,26 +1047,30 @@ implements one trait, the other, or both, depending on its declared participatio
 
 ### 9.1 Wire envelope (Rust mirror)
 
-MXC's parser at `src/core/wxc_common/src/config_parser.rs` deserializes the
-wire-format JSON directly into the typed wire model in
-`src/core/wxc_common/src/wire.rs` (`wire::MxcConfig`), then maps it into the
-typed domain models (`convert_wire_config` → `ExecutionRequest`, with `From`
-impls beside the domain types for the trivial enum/struct conversions) before
-dispatch. The state-aware path reuses this same wire model.
+`src/core/wxc_common/src/config_deserialize.rs` performs path-aware JSON
+deserialization into the typed wire model in
+`src/core/wxc_common/src/wire.rs` (`wire::MxcConfig`).
+`src/core/wxc_common/src/config_parser.rs` discriminates request shape,
+validates the wire model, and maps it into the typed domain models
+(`convert_wire_config` → `ExecutionRequest`, with `From` impls beside the
+domain types for trivial enum/struct conversions). The state-aware path reuses
+this wire model while retaining its per-backend `experimental` subtree for
+dispatch-time typing.
 
 ```rust
 // In config_parser.rs — discrimination is by presence of the `phase` key in
-// the decoded JSON; both shapes deserialize into the one wire::MxcConfig type,
-// which declares `phase` / `sandboxId` and the per-backend `experimental` block.
-let value: serde_json::Value = serde_json::from_str(&json_str)?;
-if value.get("phase").is_some() {
-    // state-aware: peel off the raw `experimental` block (typed per-backend at
-    // dispatch), deserialize the rest into wire::MxcConfig, then map.
-    convert_wire_state_aware(value, logger, allow_missing_command)
+// the source JSON without building a full untyped request tree.
+let discriminator: RequestDiscriminator<'_> =
+    config_deserialize::from_str(&json_str)?;
+if discriminator.phase.is_some() {
+    convert_wire_state_aware(
+        &json_str,
+        discriminator.experimental,
+        logger,
+        allow_missing_command,
+    )
 } else {
-    // one-shot: deserialize wire::MxcConfig from the source text (preserving
-    // serde line/column diagnostics) and map.
-    let cfg: wire::MxcConfig = serde_json::from_str(&json_str)?;
+    let cfg: wire::MxcConfig = config_deserialize::from_str(&json_str)?;
     convert_wire_config(cfg, logger, true, allow_missing_command)
 }
 ```
@@ -1073,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.
 
@@ -1426,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

docs/versioning.md

@@ -438,6 +438,16 @@ HRESULT EnumerateSandboxSpecVersionInfo(
 
 Negotiation failures are **typed and actionable** — never a silent fallback:
 
+- **JSON and policy-shape failures** distinguish malformed JSON syntax from
+  valid JSON that does not match the typed wire contract. Typed failures name
+  the full policy path (for example, `network.proxy.localhost`), retain Serde's
+  expected type/value information, and include source line/column when parsing
+  directly from request text. State-aware per-backend configuration errors are
+  prefixed with their full `experimental.<backend>.<phase>` location. Diagnostic
+  text escapes control characters, and errors at secret-bearing paths redact the
+  submitted value. After the root JSON value, only whitespace is accepted;
+  trailing JSON values or other trailing content are rejected as malformed
+  syntax.
 - **Schema-range failures** (Stage 1) carry a clear "older than supported" /
   "newer than supported" message telling the caller whether to update the config
   or upgrade `wxc-exec`.

src/Cargo.lock

@@ -96,6 +96,8 @@ windows = { version = "0.62", features = [
 windows-core = "0.62"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+serde_path_to_error = "0.1"
+unicode-general-category = "1"
 thiserror = "2"
 anyhow = "1"
 base64 = "0.22"

src/Cargo.toml

@@ -5,8 +5,8 @@
 //!
 //! The single home for resolving a parsed state-aware request to its backend
 //! and driving the per-phase flow. It centralizes the backend-specific
-//! construction that previously lived inline in `wxc-exec` so the binary can
-//! shrink to a thin CLI shell.
+//! construction that would otherwise live inline in `wxc-exec` so the binary
+//! can shrink to a thin CLI shell.
 //!
 //! Backends whose `StatefulSandboxBackend` impl lives in a `backends/*` crate
 //! (which depends on `wxc_common`, so the construction can't live inside
@@ -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/mxc_engine/src/state_aware.rs

@@ -233,7 +233,7 @@ fn apply_command_override(
     }
 }
 
-/// The correlation-vector action a state-aware phase should take, decided purely
+/// The plan for producing this phase's correlation vector, derived
 /// from the phase and the relayed value. Returned by [`plan_correlation_vector`]
 /// so the seed-vs-spin decision is unit-testable without touching the RNG/clock;
 /// the caller executes the plan against the (nondeterministic) operators.
@@ -301,6 +301,16 @@ fn inject_correlation_vector(outcome: &mut Result<DispatchOutcome, MxcError>, cv
     }
 }
 
+/// On a state-aware dispatch failure, record the error only on the auxiliary
+/// diagnostic sinks (`--log-file` and the diagnostic pipe) via
+/// [`Logger::log_diagnostic_line`]. It is deliberately kept out of the primary
+/// console/buffer output so it never interleaves with the stdout response
+/// envelope; the failure reason still reaches the client through the JSON error
+/// envelope on stdout.
+fn log_state_aware_dispatch_error(logger: &mut Logger, error: &MxcError) {
+    logger.log_diagnostic_line(&error.to_string());
+}
+
 /// Drives the state-aware dispatch flow. On envelope success, writes the
 /// JSON to stdout and exits 0. On exec success, exits with the script's
 /// exit code (output already streamed). On failure, writes a JSON error
@@ -401,6 +411,13 @@ fn run_state_aware_main(
         elapsed,
     );
 
+    // On dispatch failure, route the error to the auxiliary diagnostic sinks
+    // only (log file / diagnostic pipe) — never the primary buffer/stderr — so
+    // the stdout error envelope written below stays the single client-facing
+    // channel and is not shadowed by a duplicate on stderr.
+    if let Err(error) = &outcome {
+        log_state_aware_dispatch_error(logger, error);
+    }
     // Diagnostic buffer flushes to stderr regardless of success/failure so it
     // never interleaves with the stdout envelope.
     let buffered = logger.get_buffer().to_string();
@@ -1212,17 +1229,16 @@ fn main() {
         }
         mark_audit_active();
         _audit_guard = Some(AuditTraceGuard);
-        // previously this was
-        // `let _ = run_plm_command(...)`, which discarded the failure
-        // status. If plm start failed (missing plm.exe, wpr session
-        // conflict not resolved, etc.), the workload ran with
-        // `permissiveLearningMode` injected into the sandbox policy
-        // but with zero WPR recording — an empty Adjusted_*.json
-        // looked like "no denials." Bail explicitly on start failure
-        // so the operator sees the error and the policy isn't
-        // silently relaxed.
+        // Bail explicitly on `plm start` failure rather than
+        // discarding the failure status. If plm start failed
+        // (missing plm.exe, wpr session conflict not resolved,
+        // etc.), the workload would run with `permissiveLearningMode`
+        // injected into the sandbox policy but with zero WPR
+        // recording — an empty Adjusted_*.json looks like "no
+        // denials." Bailing lets the operator see the error and the
+        // policy isn't silently relaxed.
         //
-        // bracket the spawn with
+        // Bracket the spawn with
         // AUDIT_START_IN_FLIGHT so the console-control handler waits
         // for it to drain before deciding whether to issue `wpr
         // -cancel` (closes the Ctrl+C race where cancel arrives
@@ -1267,13 +1283,13 @@ fn main() {
     // its exit code. Done before the runner is dropped so the trace
     // tooling sees a fully-quiesced workload.
     //
-    // only clear `AUDIT_ACTIVE` when `plm stop` actually
-    // succeeded. Previously the flag was cleared unconditionally,
-    // which silently leaked the kernel ETW session whenever stop
-    // failed (missing plm.exe, spawn fail, wpr -stop non-zero) and
-    // simultaneously turned `AuditTraceGuard::drop` and the Ctrl-C
-    // handler into no-ops. On failure we now leave the flag set so
-    // the stack guard's `Drop` runs `wpr -cancel` for us.
+    // Only clear `AUDIT_ACTIVE` when `plm stop` actually
+    // succeeded. Clearing it unconditionally would silently leak
+    // the kernel ETW session whenever stop failed (missing
+    // plm.exe, spawn fail, wpr -stop non-zero) and simultaneously
+    // turn `AuditTraceGuard::drop` and the Ctrl-C handler into
+    // no-ops. On failure, leave the flag set so the stack guard's
+    // `Drop` runs `wpr -cancel` for us.
     #[cfg(target_os = "windows")]
     if cli.audit {
         let mut stop_args: Vec<std::ffi::OsString> = vec![std::ffi::OsString::from("stop")];
@@ -1381,6 +1397,31 @@ mod tests {
         Logger::new(Mode::Buffer)
     }
 
+    #[test]
+    fn state_aware_dispatch_errors_use_only_auxiliary_diagnostic_sinks() {
+        let directory = tempfile::tempdir().unwrap();
+        let log_path = directory.path().join("mxc.log");
+        let mut logger = test_logger();
+        logger.enable_file_sink(&log_path).unwrap();
+        let error = MxcError::malformed_request(
+            "Invalid configuration at `experimental.wslc.start.portMappings[0].windowsPort`",
+        );
+
+        log_state_aware_dispatch_error(&mut logger, &error);
+
+        assert!(
+            logger.get_buffer().is_empty(),
+            "the JSON envelope must retain primary output ownership"
+        );
+        drop(logger);
+        let log = std::fs::read_to_string(log_path).unwrap();
+        assert_eq!(
+            log.matches("experimental.wslc.start.portMappings[0].windowsPort")
+                .count(),
+            1
+        );
+    }
+
     #[test]
     fn cli_parses_flags_after_config_path_without_command_override() {
         let cli = parse_cli(&["wxc-exec", "policy.json", "--experimental", "--debug"]);
@@ -1671,6 +1712,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/src/main.rs

@@ -12,7 +12,9 @@ schema-gen = ["dep:schemars"]
 
 [dependencies]
 serde = { workspace = true }
-serde_json = { workspace = true }
+serde_json = { workspace = true, features = ["raw_value"] }
+serde_path_to_error = { workspace = true }
+unicode-general-category = { workspace = true }
 thiserror = { workspace = true }
 base64 = { workspace = true }
 url = { workspace = true }