TL;DR

__repr__ in rust-bindings/src/sessions/ was built with format!("{:?}"), which is not a Python literal writer. Rust renders a non-printable non-ASCII character as \u{a0}; Python requires exactly four hex digits after \u, so the repr does not parse. A job whose stdout contains a no-break space is enough to produce one. Every string field now goes through CPython's own repr(), so the escaping is by construction whatever the running interpreter produces.

6 sites, 176 new tests, 5 independent mutants. Rebased onto efba36c (0.11.11).

Review round added: a PathMappingRule repr that corrupted Windows paths silently, a panic path in the new helper, a mutex held across a CPython call, a Session keyword that did not match its constructor, and ESC coverage — see Review round.

Reproduction from a job template

This is a valid, unremarkable 2023-09 template. Nothing here is adversarial — the action prints a no-break space, the kind of thing that arrives from a localised DCC message, a copied filename, or a progress line.

specificationVersion: jobtemplate-2023-09
name: ReprEscapingDemo
steps:
- name: PrintNonAscii
  script:
    actions:
      onRun:
        command: python
        args:
        - -c
        - print("render complete\u00a0100%")

A consumer runs the action, captures stdout, and wraps it in an ActionResult — then logs it:

result = ActionResult(state=ActionState.SUCCESS, exit_code=0, stdout=captured)
repr(result)

Measured, running the template's action for real and reverting only ActionResult::__repr__:

The captured stdout is identical in both runs ('render complete\xa0100%\n'). Only the repr differs.

Why it fails — the call stack

  logging / f-string / pytest assertion
    └─ repr(action_result)                     Python
        └─ tp_repr slot                        CPython, dispatched by PyO3
            └─ PyActionResult::__repr__        rust-bindings/src/sessions/types.rs:528
                └─ format!("... stdout={:?}", self.stdout)
                    └─ <str as Debug>::fmt     Rust std
                        └─ char::escape_debug_ext per char
                            └─ non-printable  ⇒ writes  \u{a0}      ← Rust syntax
        ⇒ String handed back to CPython as the object's repr
            └─ anything parsing it: ast.literal_eval / eval / doctest / a
               reader copying it back into code
                └─ Python's \u escape wants exactly 4 hex digits, finds '{'
                    ⇒ SyntaxError: truncated \uXXXX escape

The divergence is narrow, which is why it survived. Rust's Debug for str special-cases only the quote, the backslash, and NUL/tab/CR/LF — those come out Python-legal, NUL as \0 which Python reads as octal. Every other control falls through to the brace form, including ESC. Measured with a standalone Rust binary:

ESC is the one that matters most in practice: ActionResult.stdout is captured process output, and ANSI colour sequences are ordinary content there — almost certainly the highest-frequency trigger in the field. Every quick check with a newline or a quote passes, which is why this survived.

Two further defects lived in the same format! expressions, and are fixed with it — leaving them would have kept the repr un-evaluable and cost the round-trip check that pins the escaping:

• Debug for Option emitted exit_code=Some(0) → NameError: name 'Some' is not defined.
• The state field rendered as a bare SUCCESS → also a NameError. It now uses the spelling the enum's own repr already produces, ActionState.SUCCESS.

Why the fix lives at the PyO3 layer and not in openjd-rs

Short version: __repr__ is a Python protocol and Debug is a Rust one. They are different contracts that happen to look alike. For these types there is also nothing downstream to fix, and pushing the fix down would mean reimplementing CPython's escaping in a crate that has no interpreter — when the interpreter is right there at the boundary.

  Python:  repr(action_result)
    │
    │  ── PyO3 / binding layer ─────────────────────────────────────
    ├─ PyActionResult::__repr__          rust-bindings/src/sessions/types.rs
    │     struct PyActionResult { state, exit_code, stdout }   ← defined HERE
    │     emits: "ActionResult(state=..., exit_code=..., stdout=...)"
    │              └─ Python constructor keywords, from #[new]'s signature
    │
    ├─ py_repr::py_str(py, s)            rust-bindings/src/py_repr.rs   ← THE FIX
    │     └─ PyString::new(py, s).repr()
    │          └─ CPython's own repr        needs Python<'_>; exists only here
    │
    │  ── openjd-rs (no interpreter, no Python concepts) ───────────
    └─ openjd_sessions::ActionResult      openjd-sessions-0.5.7/src/action.rs:74
          pub struct ActionResult { state, exit_code, stdout }
          #[derive(Debug)]  →  "a\u{a0}b"   ← correct Rust, round-trips in Rust

Three consequences of that shape:

For ActionResult there is no downstream to fix. PyActionResult is its own struct with its own fields, not a newtype over openjd_sessions::ActionResult. The object being repr'd does not exist in openjd-rs. And openjd_sessions::ActionResult's derived Debug is not wrong — "a\u{a0}b" is a legal Rust literal that round-trips in Rust, so a Rust consumer is served correctly today and this PR changes nothing for it.

The string is Python-specific even where a wrapper does exist. PathMappingRule(source_path_format=PathFormat.POSIX, source_path=...) names the Python constructor's keyword arguments and the Python enum's spelling. openjd-rs has no PathFormat.POSIX and no keyword arguments; teaching it those would be teaching a Rust crate about a Python API it does not have.

Pushing down means reimplementing, not moving. CPython's repr() needs a Python<'_> token, which exists only above the FFI boundary. Without one you must hand-roll the escaping plus a unicode printability table that tracks the CPython version — which is exactly what openjd-expr/src/py_escape.rs is, 465 lines. A reimplementation can drift from the interpreter; the interpreter's own repr cannot.

That also answers the suggestion on #359 of routing through the writer openjd-rs#374 added. Beyond the layering argument, it is not reachable from this crate:

openjd-expr-0.7.0/src/lib.rs:27:      pub(crate) mod py_escape;
openjd-expr-0.7.0/src/py_escape.rs:33: pub(crate) fn write_py_string_literal(...)

SymbolTable.__repr__ already delegates to Python's repr, so the pattern is established in this crate.

Where openjd-rs is the right layer

The inverse case exists, and it is why #374 lives upstream rather than here. repr_py is a template-callable function whose output is fixed by Expression Language §2.2.6: a template rendered by the Rust openjd CLI must produce byte-identical output to one rendered through Python. That contract spans both runtimes, so it cannot live in a Python binding — and because the CLI has no interpreter, it has to be reimplemented. The 465 lines are a cost worth paying there and not here.

The rule that separates the two: spec-mandated Python output belongs in Rust and must be reimplemented; Python-protocol output belongs at the binding and should delegate to the interpreter.

The cost of that split, stated plainly

It leaves two escaping implementations in one package: py_escape behind ExprValue.__repr__ and repr_py, and CPython's real repr() behind the sessions reprs. If py_escape ever diverged from CPython, those two families of repr would disagree. They agree today — ExprValue's repr was checked against CPython's on 31 inputs during the #359 bump and all matched — but nothing currently tests the two implementations against each other, so this is knowledge rather than a guarantee.

Sites

SessionState.__repr__ and ScriptRunnerState.__repr__ were already correct and are untouched.

Reachability

ActionResult.stdout is populated by the consumer, not by this binding — SessionConfig.debug_collect_stdout is hardcoded false here, and the binding never constructs a PyActionResult itself. The type is public and documented for exactly this use ("user code can also construct one directly"), and a worker agent that captures output and builds one hits the defect with any non-ASCII byte in a job's stdout.

PosixSessionUser carries a user name supplied by the caller. Worth noting for the threat model: template validation rejects only Cc control characters, so U+00A0 and U+3000 — both Zs — pass through step and job names untouched.

Tests

Adds test/openjd/sessions/, which did not exist; the sessions surface had no Python tests beyond a module-name check.

176 cases over 19 inputs: the characters Rust renders as \u{...}, the ones Debug does escape correctly (kept as controls against a hand-rolled replacement getting them wrong), printable non-ASCII that must survive verbatim, and negative controls for text needing no escaping. group is asserted separately from user because a fix applied to only the first argument would pass every user case.

Mutation-checked with each behaviour reverted independently against a green 113-case baseline. Each mutant tree was confirmed to build and import first, so no verdict is a disguised compile error:

Verification

• cargo build, cargo fmt --check, cargo clippy --all-targets — clean
• Full suite: 5971 passed, 24 skipped, 3 xfailed, coverage 94.14% against the 94% gate. The 3 xfails are pre-existing and unrelated.
• black --check, ruff check, mypy — clean
• CI on the previous revision: 30/30 checks green, all six Windows Python jobs passing. The Windows run confirmed the posix gating works — skips went 1 → 50 with passed unchanged at 5882, i.e. exactly the 49 previously-failing tests, nothing dropped from collection.
• No stub regeneration needed: a Python<'_> token is invisible to Python and PyResult<String> still maps to str. SymbolTable.__repr__ already uses this form and its stub entry is def __repr__(self) -> builtins.str.

Unverified: WindowsSessionUser's escaping. Off the process user its constructor demands a password or a logon token, so it cannot be built with an arbitrary name just to read its repr. It shares the helper the other three string sites test. I did not add a conditionally-skipping test that would pass everywhere while asserting nothing.

Scope

sessions/ only. The same patterns exist at ~13 sites under rust-bindings/src/model/ and 2 under rust-bindings/src/expr/ — including the FormatString.__repr__ originally flagged on #359, which escapes nothing at all, not even the quote. Those are follow-ups reusing the py_repr helper this PR introduces. Independent of #359; rebased onto mainline at the 0.11.11 release.

Review round

Five defects found by review on the first revision, each measured before fixing. Two were introduced by this PR's own fix, which is the part worth noting — routing a repr through CPython changes what can run while a lock is held, and the helper became a new single point of failure.

PathMappingRule corrupted Windows paths silently (expr/path_mapping.rs). Not a {:?} at all — it hand-rolled '{}' with no escaping, so it was invisible to the grep that found the others. Measured:

This is the only repr found that corrupts on its most typical input — a Windows destination path is what path mapping exists to produce. Everything else in this bug class fails loudly at compile(). Pulled into this PR ahead of the model/ queue for that reason.

py_repr::py_str could panic instead of raising. .to_string() on a Bound<PyString> resolves to PyO3's Display, which calls str() and has nowhere to put a PyErr — ToString treats the formatter error as unreachable and panics. An unwind out of __repr__ across the FFI boundary, in the function every repr routes through, on a path reached mostly from logging and exception formatting. Now to_cow()?, which reads the UTF-8 directly and propagates.

Session.__repr__ held the snapshot mutex across the CPython call. New with this fix: the old format!("{:?}") touched no interpreter state. py_str allocates, allocation can trigger a GC pass, and a finalizer run by that pass can re-enter this Session and re-lock a non-reentrant Mutex. lock_recover maps a poisoned lock to into_inner(), so that failure would be silent. Fixed by reading out from under the guard and dropping it first; recorded in the helper's docs as a rule for the model/ follow-up.

Session.__repr__ used id=, not session_id=. It parsed and then raised TypeError: got an unexpected keyword argument 'id' — moving the failure from compile time to call time, which is worse than what it replaced.

ESC was missing from the test inputs, and the docs implied only non-ASCII was affected. Added ESC, U+0001 and U+001F. "a\x00b" was also mislabelled as representative of C0 when it passes only because NUL has its own arm.

Two claims of mine that were wrong, now corrected:

• A test comment said ActionStatus has no __eq__. It does (types.rs:337), comparing seven fields; the repr emits two, so it is evaluable but does not round-trip — and cannot be made to, since started_at/ended_at are not constructor arguments. The misleading eval() is replaced by test_repr_omits_fields_that_eq_compares, which pins the lossiness.
• py_repr's docs said delegating "retires the bug class". It retires it for sessions/ only. Wording narrowed and the remaining surface named.

Coverage added for Session and PathMappingRule, which the first revision omitted — both are constructible in a unit test, so those were oversights rather than constraints. Session skips the NUL case: the id becomes a working-directory path component and the filesystem rejects it before any repr is taken.

Evidence the PathMappingRule change is a no-op for well-behaved input: the pre-existing TestPathMappingRuleRepr in test/openjd/expr/test_path_mapping.py passes unmodified.