# Apple NSXPC transport for Rust OXC

## Traceability
- Spec ID: apple-nsxpc-oxc-service
- Status: Implemented
- Request: implement Apple NSXPC; all capability services use Rust.
- Implementation: Codex; no external Story/issue was supplied.

## Intent
Run macOS desktop OXC parse/transform through an actual bundled Foundation
NSXPC service, keeping the existing Node semantic compiler and Windows/Linux
Rust stdio transport.

## Acceptance Scenarios
- AC-1: A Rust client connects using NSXPCConnection to a launchd-started Rust
  service in Contents/XPCServices. Real parse/transform replies identify a
  service PID distinct from the client and Studio process.
- AC-2: Only a bounded versioned NSData request/reply method is exported; the
  existing source, filename, operation and output limits remain enforced.
- AC-3: Connection failure and deadlines fail pending work without replay or
  silent stdio fallback. Closing a compiler closes its bridge/connection; a new
  compiler can reconnect after a service crash. Service lifetime belongs to
  launchd, not to the Node process PID owner.
- AC-4: Development and packaged macOS app both discover the bundled service.
  Windows/Linux preserve the current executable and stdio contract.
- AC-5: Native tests prove OXC parity, native transport identity and failure
  recovery; packaged Electron smoke proves NSXPC use without OXC NAPI loading.

## Non-goals
ACP extraction, Node host replacement, public Mach services, distribution
signing/notarization, auto-update, renderer IPC migration, and new OXC language
semantics.

## Plan and Tasks
- Share Rust compiler core between stdio and NSXPC entry points.
- Use Foundation bindings from Rust for listener, exported object and client;
  a declaration-only Objective-C file emits Clang protocol metadata, and the
  Rust reply block supplies an explicit NSData ABI signature;
  retain a small bounded stdio bridge at the Node boundary. It performs no
  compilation and communicates with the service exclusively over NSXPC.
- Bundle a private helper app for development; put the client in the packaged
  app executable directory and the service in its XPCServices directory.
- Carry transport and native service identity separately from bridge PID.
- Add packaging, connection lifecycle and real native integration receipts.

## Test and Review Evidence
Local validation on macOS arm64 with Xcode 26.6, Rust 1.96.0 and Electron
44.2.0 (embedded Node 24.20.0):

- AC-1/AC-4/AC-5: `npm run better-harness-desktop:pack` passed. Development
  `npm run smoke -w @qoder-ai/better-harness-desktop` and packaged
  `node packages/better-harness-desktop/scripts/smoke.mjs --packaged` passed.
  Packaged receipt: main PID 19616, Studio PID 19681, bridge PID 19684,
  NSXPC service PID 19685, transport `nsxpc`, OXC NAPI not loaded. Renderer
  isolation, authenticated HTTP, directory flow, three viewport screenshots,
  error-free page and host/bridge shutdown checks passed. Receipt and images
  are generated under `packages/better-harness-desktop/dist/smoke`.
- AC-2/AC-5: `npm run test:rust -w @qoder-ai/better-harness-desktop`: 5 passed.
  Shared compiler behavior is preserved by moving it into the Rust library.
- AC-2/AC-3/AC-4/AC-5: `npm run test:native -w @qoder-ai/better-harness-desktop`:
  16 passed, exercising stdio and NSXPC semantic parity, HTTP build/preview,
  concurrent correlation, malformed output, cancellation, deadlines, actual
  SIGSTOP/SIGKILL of the NSXPC service, reconnection, and refusal of stdio when
  NSXPC is required.
- AC-4: `npm run better-harness-desktop:test`: 6 passed. `codesign --verify --strict`
  passed for the packaged XPC bundle (ad-hoc signature).
- Repository checks: `npm run preview`, `/health` and `/canvas-module.js` both
  HTTP 200; owned preview process stopped. Documentation routing regenerated
  without diff; `npx vitest run test/skills-docs/doc-link-graph.test.mjs`:
  8 passed. `git diff --check` passed.

An initial development smoke overlapped build output cleanup and timed out;
its isolated rerun after build completion passed. Future build and smoke runs
must be sequential. An initial native probe exposed a missing Rust reply-block
signature; the explicit NSData encoding fixes the actual Foundation exception.

## Review Readiness

Request/spec/implementation/tests match AC-1 through AC-5. Changed modules are
Rust compiler transport, desktop packaging/lifecycle, the Studio native adapter,
focused tests and documentation. Cargo.lock contains native binding/build
requirements; generated binaries and screenshots remain ignored. No renderer
business logic or release versions changed. All changes are local and unstaged.

Windows/Linux retain stdio and platform-gated Rust imports/build behavior; their
existing desktop CI jobs remain authoritative, and were not run here. macOS
x64 was not executed locally. Distribution signing/notarization and App Sandbox
entitlements are not configured. NSXPC process lifetime belongs to launchd;
closing a compiler does not promise service exit. A 30-second native watchdog
terminates the shared service if synchronous compilation stalls, so other
connections fail too; this watchdog's hard process-exit path has not been
fault-injected (host deadline and service-kill recovery were exercised).