Rust OXC Service

Traceability

• Spec ID: rust-oxc-service
• Status: Implemented
• Request: split OXC into an XPC service; all extracted capability services must be written in Rust.
• AI involvement: Codex implementation and local validation.

Intent

Move desktop OXC native parsing and transformation into a supervised Rust executable. Preserve AgentReact profile checks, ABI extraction, semantic index, diagnostics and browser CLI compatibility.

Acceptance Scenarios

• AC-1: Desktop uses the Rust service for every OXC parse/transform, with no OXC NAPI library loaded in the Studio process. A typed compiler factory passes through production artifact routes; the browser CLI retains its worker adapter.
• AC-2: A versioned, strict, bounded JSONL stdio protocol carries request ids and parse/transform results. Invalid requests, unknown fields, oversized sources/frames and unsupported protocol versions fail closed. Native code receives source text, not filesystem authority.
• AC-3: Deadline, crash, malformed output and close settle pending calls. Timeout/cancellation kills the affected process; a later compile starts a fresh process. Queues and buffers are bounded; no automatic replay of the failed request.
• AC-4: Valid TSX (including non-ASCII text), refused profile examples, ABI/semantic index and source maps match the existing kernel. Profile refusal happens before requesting transformation. Compiler identity and outer artifact caches distinguish transports.
• AC-5: Cargo locks OXC to 0.147.0; target-native Rust binaries ship outside ASAR. Native tests and the packaged macOS app prove real service calls and process separation. Windows/Linux build and smoke are wired into CI; unrun platforms remain unverified.

Design and Capability Matrix

Capability	Decision
Parse and transform	Rust service using pinned OXC crates
Profile, ABI, semantic index	Existing JS semantic kernel, using a private backend port
AST transfer	Bounded ESTree JSON inside the kernel/backend boundary only; never exposed to business callers or renderer. UTF-8 spans converted to UTF-16 for parity.
Cancellation	Kill dedicated compiler process; synchronous native work cannot consume cancel messages while executing
XPC transport	Cross-platform child process + framed JSONL stdio; native macOS NSXPC is not claimed
Other future capability services	Rust executables; Studio remains the existing Node host runtime

Non-goals

No ACP extraction, semantic-rule rewrite, generic RPC registry, UI changes, macOS-only NSXPC bridge, signing, publication or auto-update changes.

Plan and Tasks

1. Separate the native backend from semantic compilation without changing the existing default adapter. Keep constants available without importing NAPI.
2. Add Rust parse/transform service and a supervised Node transport adapter.
3. Inject compiler factory from desktop through Studio production routes; partition caches by factory and retain current OxcCompilerPort output.
4. Package the Rust binary as an external resource; add Cargo/native/protocol parity checks and extend desktop smoke with actual Rust proof.

Test and Review Evidence

Local macOS arm64 evidence on 2026-09-07:

Acceptance	Receipt
AC-1	Packaged-app smoke records separate main, Studio and Rust PIDs; Studio process.report sharedObjects contains no OXC NAPI. Native HTTP test proves both build and preview routes call the injected compiler.
AC-2	Five Rust tests cover UTF-16 spans, TSX transform/source map, unknown methods/fields/versions, source limits, oversized/truncated frames and parse errors. Cargo.lock pins native dependencies.
AC-3	Native adapter tests exercise a hung child, exit code zero, malformed JSON, oversized stdout, cancellation, use after close and recovery with a real Rust process. Desktop tracks active compilers and closes them before stopping Studio.
AC-4	Seven native integration tests include parity with NAPI over valid and refused inputs, Unicode, generated code and parsed source maps; profile refusal makes zero transform calls. Artifact cache regression proves different factories cannot share cached builds.
AC-5	Full desktop build/stage/pack and packaged macOS arm64 smoke pass. Binary ships outside ASAR. Cargo tests, native integration tests and packaged smoke are wired into the three-platform CI matrix.
Regression	AgentReact/artifact/auth selection: 182 passing tests before adding the cache case. Final artifact/project/server selection: 70 passing tests including that new case. These overlap and are not additive. Six desktop lifecycle tests and eight docs-link tests also pass.

Commands: npm run test:rust -w @qoder-ai/better-harness-desktop, npm run test:native -w @qoder-ai/better-harness-desktop, npm exec -w @qoder-ai/harness-studio -- vitest run test/agent-react test/artifact-compile-runtime.test.ts test/desktop-authorization.test.ts, npm exec -w @qoder-ai/harness-studio -- vitest run test/artifact-compile-runtime.test.ts test/project-server.test.ts test/server.test.ts, CSC_IDENTITY_AUTO_DISCOVERY=false npm run better-harness-desktop:pack, npm run smoke -w @qoder-ai/better-harness-desktop -- --packaged.

Generated native and screenshot/JSON receipts live under the desktop package's ignored dist/. Windows/Linux jobs have not run here; no signed release or native Apple NSXPC acceptance is claimed. Existing Studio npm dependencies retain NAPI for browser/CLI compatibility, but the desktop does not load or fall back to those modules. AST serialization adds bounded transport overhead; no speedup is claimed. Source-map object content matches; JSON property ordering is not a semantic equality requirement.

Review Readiness Check: user request and spec confirmed; no Story supplied. The Electron baseline is committed as 3920fd1. This Rust slice is reviewed separately from the baseline: native service/lockfile, semantic-backend seam, supervised adapter, factory routing/cache isolation, desktop packaging/smoke, architecture rule and tests. No ACP implementation or UI change is included. No generated runtime artifacts are staged; no publication is performed.