Build the shared PTY compatibility and conformance corpus

[schickling-assistant]

Outcome

pty-rust owns one versioned compatibility corpus for the current PTY protocol.

The Node PTY and pty-rust must run the same transport and terminal behavior cases. pty-layout is a reference client and a source of real fixtures. Fractal can use the client cases that apply to an embedded terminal.

Ownership

• This issue owns the corpus and its expected results.
• Node PTY is the current behavior reference.
• pty-rust is the new implementation target and long-term corpus owner.
• pty-layout is a proven reference client and fixture source.
• Fractal is an embedded-client consumer.
• A difference between Node and Rust must be written down as a decision. It must have a test.

Attach identity contract

• Declared PTY root plus session ID means the current session at that address.
• A replacement can use the same root and session ID.
• A new attach must resolve that replacement.
• Generation is optional diagnostic data. It is not attach eligibility.
• Clients use a local AttemptId or epoch to reject delayed events from older attempts.
• A missing generation in list or stats is valid current Node PTY behavior.

Required fixtures

• Split each UTF-8 scalar at every byte boundary.
• Split each terminal escape sequence at every byte boundary.
• Cover Kitty keys, Alt keys, mouse input, focus input, and bracketed paste.
• Give malformed UTF-8 one clear expected result.
• Cover raw bytes from 0x80 through 0xff. Record the current Node and Rust difference.
• Cover attach by declared root and session ID with no generation in list or stats.
• Replace a session under the same root and ID. Prove that a new attach reaches the replacement.
• Delay readiness, output, and outcome events from an old local attempt. Prove that they cannot update the new attempt.
• Cover attach, initial screen, resize, live data, detach, exit, and reconnect order.
• Cover frame chunking and frame size limits.
• Cover a slow reader without blocking other clients.
• Cover exact input bytes.
• Cover relay over SSH and WebSocket without a change to terminal behavior.
• Publish a checked Node and Rust result from the same corpus version.

Reference-client fixtures

• Extract useful black-box cases from pty-layout.
• Keep terminal-specific cases for Kitty, Ghostty, resize, and cleanup.
• Add a regression case only when it describes an observed behavior or a stable contract.
• Let Fractal consume the input, identity, scroll, resize, detach, exit, and reconnect cases that apply to it.

Input contract

The current wire frames stay byte-oriented. Normal interactive terminal text is UTF-8 plus terminal control sequences.

• Buffer incomplete UTF-8 across reads.
• Report malformed input. Do not silently replace it.
• Do not add a stateful binary switch now.
• Add binary input only after a real program needs exact byte round trips and all claimed backends can pass the same fixture.

Acceptance

• The corpus has a version and a stable fixture format.
• Node PTY and pty-rust run the same required fixtures.
• Attach parity preserves root-plus-session-ID current-session behavior.
• No conformance fixture requires generation discovery or generation-fenced admission.
• Optional observed generation can appear in diagnostic output without changing eligibility.
• pty-layout reference cases are represented without making Node code the corpus owner.
• Fractal can reuse the client fixtures without a second behavior definition.
• Every intentional Node and Rust difference has a decision record and a test.
• CI shows the implementation name, corpus version, and result.

Related

• Parent: Define Node compatibility contract and export an embeddable PTY client crate #1
• Embedded handle: Export one embedded terminal API for attached and spawned PTYs #3
• Replaces: Specify terminal DATA byte semantics and add Node/Rust conformance fixtures pty#160
• Input design resolution: Design question: intended input boundary for embedded PTY clients pty#155
• Reference client: Capture pty-layout as a reference embedded-client conformance target pty-layout#1
• Fractal migration: schickling/dotfiles#1378