# Z9: RV7 gaps and the string-field decode audit

Builds on `final-Z7.md` / `final-Z8.md` (`EncodedOs`, the reversible `U+FDD0`
escape in `ghostty_os::osbytes`). Contract used below:

* **encoded** = a config/CLI `String` in the reversible encoding. It must be
  decoded (`EncodedOs::{to_os,to_path,to_bytes,to_wide}`,
  `config_str_to_bytes`, or for UTF-8-only UI text `config_str_to_text`) before it
  reaches the OS, the pty, the clipboard, or C.
* **plain** = real text; it may only become an encoded value through
  `from_plain_text` / `valid_str_to_config_string` (escapes a literal `U+FDD0`).

New helpers: `osbytes::{InvalidWtf8, try_wtf8_to_wide, config_str_to_text}`,
`EncodedOs::{try_to_wide, try_to_wide_nul, try_to_os}`,
`ghostty_config::string::parse_bytes`, `ghostty_os::windows_nls::upcase_w`.

## 1. The nine RV7 gaps

| # | Fix | Test |
|---|---|---|
| 1 Windows env key casing | `windows_nls.rs` is a port of `std/os/windows/nls.zig` (the 2544-entry `l_intl.nls` table and `upcaseW`); `EnvMap` keys use it per UTF-16 unit instead of `char::to_uppercase` | `windows_nls::tests::*`, `env::windows_key_tests::keys_use_the_windows_table_not_unicode_mappings` (U+1F80 == U+1F88, Georgian distinct, no `ß` == `SS`) |
| 2 Windows locale init | `locale.rs` `posix` module now also builds on Windows: `setlocale` with Zig's literal `LC_ALL = 6` (the UCRT rejects it exactly like Zig, so the chain continues) and `_putenv_s` for the `LANG` updates (unsafe with SAFETY comments). `ensure_locale` is only a no-op on wasm | the mock-`Sys` chain tests run everywhere; Windows glue compiled by `check-windows` |
| 3 bash `--rcfile` | `GHOSTTY_BASH_RCFILE` = `EncodedOs::from_encoded(arg).to_os()` | `bash_rcfile_keeps_original_bytes` (byte FF, literal U+FDD0) |
| 4 configured `TERM` | termio `Config.term` is now `EncodedOs`; Unix exports `to_os()`, Windows `try_to_os()?` | `configured_term_is_exported_decoded` |
| 5 GTK inherited `LANG` | `saved_language` is `Option<OsString>` read with `var_os`; the `language` config override is decoded; `set_env` takes `AsRef<OsStr>`; env restore factored into `restore_language` | `inherited_lang_keeps_non_utf8_bytes` |
| 6 Windows Kitty paths | `os_path_from_bytes`: Unix bytes, Windows WTF-8 via `EncodedOs::try_to_os` (lone surrogates ok, malformed -> `InvalidData`, no empty-path fallback) | `payload_path_bytes_are_kept` |
| 7 malformed WTF-8 | `try_wtf8_to_wide` (strict; lossy `wtf8_to_wide` kept for non-launch use). `Command::start` (path, cwd, argv) uses `try_to_wide*` -> `StartError::InvalidWtf8`; the Windows exec env block/overrides/`GHOSTTY_RESOURCES_DIR`/`TERM`/`TERMINFO`/`PWD` use `try_to_os` -> `Error::InvalidWtf8` | `strict_wtf8_rejects_malformed_input`, `malformed_wtf8_env_overrides_fail` (cfg(windows)) |
| 8 embedded C API | `ghostty_surface_complete_clipboard_request` passes bytes (`CoreSurface::complete_clipboard_request` / `Surface::complete_clipboard_request` now take `&[u8]`; the confirm callback gets the caller's `text` pointer unchanged); `ghostty_surface_binding_action` encodes the bytes with `bytes_to_config_string` before `Action::parse` | `clipboard_completion_and_binding_action_keep_raw_bytes` (child receives `61 ff` / `62 ff`) |
| 9 text/csi/esc bindings | `Text` uses new `string::parse_bytes`; `Csi`/`Esc` write `config_str_to_bytes(data)` (128-byte limit applies to bytes). `string::parse` now escapes a literal `U+FDD0` that an escape sequence produces | `config_loaded_text_csi_esc_write_decoded_bytes`, `string::tests::parse_bytes_decodes_the_reversible_encoding` |

## 2. Systematic audit: config fields -> consumers -> decode status

"OK" = decoded at the boundary (or is the typed `EncodedOs`/bytes); "plain" =
guaranteed text with no OS meaning; "FIXED" = changed in Z9.

| Field / type | Consumers that reach OS / pty / clipboard / C | Status |
|---|---|---|
| `language` (String) | GTK `LANG` override | FIXED (decoded; was raw encoded) |
| `font-family*` (RepeatableString) | `Descriptor.family` -> fontconfig / CoreText | FIXED (`config_str_to_text` in `shared_grid_set::Key::new`; font names are UTF-8 for every backend) |
| `font-feature` | HarfBuzz/CoreText feature tags | plain (ASCII tags parsed from text) |
| `font-variation*`, `font-codepoint-map`, `adjust-*`, `font-style*` | descriptors/metrics | plain (tags, numbers, names) |
| `clipboard-codepoint-map` replacement | clipboard text from the formatter | FIXED (`decode_codepoint_map`; the formatter emits text, so non-UTF-8 replacement bytes can only become U+FFFD, a literal U+FDD0 is restored) |
| `title` | `SetTitle` action (all apprts, C `set_title`) | FIXED (`config_str_to_text` in core + GTK window) |
| `class` | GTK application id (`id_is_valid`) | plain (must be an ASCII-ish app id; encoded junk is rejected as invalid) |
| `window-title-font-family` | GTK CSS | FIXED (decoded) |
| `gtk-quick-terminal-namespace` | layer-shell namespace (`&str` API) | FIXED (decoded text) |
| `macos-custom-icon` | only via C `ghostty_config_get` | OK (`config_capi::cstring_value` decodes) |
| `term` | child env `TERM` (Unix, Windows) | FIXED (`EncodedOs` through `exec::Config`) |
| `enquiry-response` | pty write on ENQ | FIXED (was `String::into_bytes()` of the encoded text; `DerivedConfig.enquiry_response` is now decoded `Vec<u8>`; test `enquiry_response_is_decoded_to_bytes`) |
| `command`, `initial-command` (`Command`) | exec argv/shell string, Windows `CreateProcessW`, flatpak `ay`, macOS login | OK (decoded in `command.rs` `config_str_to_bytes`; Windows strict `try_to_wide`); window title from argv[0]/`xdg-terminal-exec` is FIXED (decoded text) |
| `env` (RepeatableStringMap) | child environment | OK (Unix `config_str_to_os`; Windows strict `try_to_os`) |
| `input` (RepeatableReadableIO) | pty write; file read | `Raw`: OK (decoded after `clone_parsed`). `Path`: FIXED, now typed `EncodedOs` (was opened undecoded); embedded `initial_input` escape works on bytes (`string_escape`) so `parse_bytes(string_escape(b)) == b`; test `initial_input_escape_round_trips_bytes`, `readable_io_path_decodes_to_the_original_bytes` |
| `link` regex | onig regex over terminal text | FIXED (decoded text; a pattern byte >0x7F that is not UTF-8 cannot match terminal text anyway) |
| `working-directory`, `background-image`, `custom-shader`, `gtk-custom-css`, `bell-audio-path`, `config-file`, `theme` | filesystem | OK (typed `EncodedOs` since Z7) |
| `command-palette-entry` title/description | GTK palette labels | FIXED (decoded text); its `action` follows the keybind row |
| `keybind` payloads: `text`, `csi`, `esc` | pty | FIXED (gap 9) |
| `keybind` `search:` | search needle bytes | FIXED (decoded; the GTK search entry encodes its plain UI text with `valid_str_to_config_string`) |
| `keybind` `set_surface_title`, `set_tab_title` | `SetTitle` action | FIXED (decoded text) |
| `keybind` `activate_key_table*` | table-name lookup (config vs config) | plain/consistent (both sides encoded) |
| `keybind` `cursor_key` | pty | not config-parsable (raw `String` built in code) |
| `selection-word-chars` | codepoints | plain |
| `Diagnostic.{key,message}` | `+validate-config` stdout, `+show-face` stderr | FIXED (print decoded bytes); GUI diagnostics are display text |
| CLI/C: `ghostty_init` argv, `ghostty_config_load_file`, surface options (`working_directory`, `command`, `env_vars`, `initial_input`), `ghostty_surface_text`, clipboard completion, binding action, `ghostty_config_get`/`open_path` | | OK (bytes in, encoded or bytes) |
| C key event `text`, preedit | `String` (lossy) | documented limit: UTF-8 text by the `ghostty.h` contract (IME/key text); would need a byte `KeyEvent.utf8` across `ghostty-input` |

## 3. OS data entering the system (byte preserving)

| Source | Entry point | Status |
|---|---|---|
| process environment | `std::env::var_os` / `vars_os` everywhere (`get_env_map`, `getenv`, `homedir`, `xdg`, `shell_from_env`, TMPDIR/TMP, GTK `LANG`, `PATH`); `std::env::var` remains only for ASCII-only developer switches (`GHOSTTY_LOG`, `RUST_LOG`, `COLORFGBG`, `GHOSTTY_DEBUG_*`) | OK |
| argv | `os::args` (`args_os` / C `ghostty_init` bytes) -> `collect_config_strings` | OK |
| config files, theme files | read as bytes -> encoded strings | OK |
| passwd (`getpwuid`), `uname` | bytes -> `EncodedOs` (hostname: text for comparison) | OK |
| OSC 7 pwd, OSC 8 URIs, kitty file paths | bytes kept (`set_pwd(&[u8])`, `os_path_from_bytes`) | OK |
| GTK file drops | `os_bytes(path)` into the shell-escaped paste | OK |
| clipboard (C API, OSC 52, GTK text) | bytes (`&[u8]` in `complete_clipboard_request`; GTK text is UTF-8) | OK |
| D-Bus / flatpak | cwd and argv `ay` bytes; environment is `a{ss}` (UTF-8 by D-Bus type) | known limit |
| `+new-window` over D-Bus | arguments are GVariant strings | known limit (UTF-8 by type, as Zig) |
| Windows APIs | WTF-16 via `EncodedOs::{from_wide,to_wide}`; process launch is strict | OK |

## 4. Typed where practical

`exec::Config.term` (`EncodedOs`), `DerivedConfig.enquiry_response` (`Vec<u8>`),
`ReadableIO::Path` (`EncodedOs`), `ghostty_apprt::CoreSurface::complete_clipboard_request`
(`&[u8]`). The remaining `String` config fields are either UI/plain text (above)
or go through the generic config machinery (macro, formatter, C value) where a
newtype would touch every field; each consumer is listed and decoded at its
boundary instead.

## 5. Gate

`cargo test --workspace`, `clippy --workspace --all-targets -D warnings`,
`cargo +nightly fmt --all`, `just check-macos` (both targets), `just check-windows`,
`just check-wasm`, `+show-config --default --docs` vs `/usr/bin/ghostty` (only the
`gtk-opengl-debug` line differs): see the final report. Windows and macOS code is
compile-checked, not run natively.