[0.7] Writer must reject keys it cannot round-trip

[PHPCraftdream]

Target branch: 0.7 (breaking — calls that return Ok today would return Err).

Split out of #4. That PR carries two kinds of change: fixes that turn silent corruption into correct output (non-breaking, going to main), and this one — refusing to emit keys no form can round-trip.

The keys

Verified against main at 0.6.2 — every one of these emits happily today and re-parses to something else:

Key	Emitted	Re-parses as
""	: v	root flips Object → Array
"##note"	##note: v	pair eaten as a comment → {}
" k" / "k "	raw	edges trimmed by the parser (§ 4)
"k\nx"	raw	line split
"a,b", "a{b", …	raw	InvalidKey or structural break

The CR-in-String rule (§ 5.9.7) is the precedent: unrepresentable means error, not silent corruption.

Why breaking, and why not main

These calls succeed today. The output is wrong, but it parses — so in principle someone could be depending on it. That is the line we drew: main gets everything that was already broken beyond use (unparseable output, lost bytes), 0.7 gets the cases that quietly parsed into different data.

Depends on

Do #7 first. § 4 mandates ten key escapes and the parser accepts three; once the parser catches up, keys containing ( ) { } [ ] , become representable and drop out of this issue entirely — leaving only "", "##note", edge whitespace and line breaks. Landing this issue first would bake in refusals we are about to make unnecessary.

Definition of done

• Writer validates keys on all three surfaces (emit_canonical, serde to_string, render / to_string_force_strings) and returns a descriptive error naming the reason and the spec section.
• Regression tests in the crate: one per rejected class, per surface — asserting the error, not just "not Ok". Plus guard tests for tricky-but-representable keys so the check does not over-reject.
• Regression fixtures in ktav-lang/spec: this needs the new "unrepresentable value" fixture category (see the spec-side issue) — a JSON value plus the expected refusal. Without fixtures the other six bindings will drift, which is exactly what the conformance suite exists to prevent.

A working implementation already exists in #4 (9 tests); it needs re-basing onto 0.7 once the escape work lands.

[PHPCraftdream]

Update now that #7 is closed (0.6.3): the "Depends on" section above overstates what drops out. It says keys containing ( ) { } [ ] , become representable once #7 lands — that's only true for { } [ ] ,. ( and ) have no § 3.7 escape at all (not one of the ten: \ \, \} \] \{ \[ \n \r \. \:), so a key containing either remains genuinely unrepresentable regardless of parser/writer work. Verified: a\(b / a\)b correctly still fail with BadEscapeSequence, pinned in ktav-lang/spec#4's new invalid fixtures (unescapable_open_paren / unescapable_close_paren).

So the remaining refusal list for this issue is: "", "##note", edge whitespace, embedded line breaks, and keys containing ( or ) — not just the first four.

The writer's escape table is now the full ten (0.6.3), so , { } [ ] \n \r keys round-trip fine today and are correctly out of scope here.

[PHPCraftdream]

Correcting my own previous comment — I got one entry wrong.

I listed "embedded line breaks" as still-refusable after #7. That is false, and I should have caught it: the same 0.6.3 work added canonical_keeps_keys_with_the_seven_newly_escapable_bytes, which pins "a\nb" and "a\rb" as round-tripping. Re-verified against 0.6.3 just now:

"a\nb" -> emitted "a\nb: v\n" -> ROUND-TRIPS
"a\rb" -> emitted "a\rb: v\n" -> ROUND-TRIPS
""     -> emitted ": v\n"      -> parses to different data (root flips to Array)
"##note" -> emitted "##note: v\n" -> parses to different data (pair eaten as comment)
" k"   -> emitted " k: v\n"    -> parses to different data (edge trimmed)
"k "   -> emitted "k : v\n"    -> parses to different data (edge trimmed)
"a(b"  -> emitted "a(b: v\n"   -> UNPARSEABLE (InvalidKey)
"a)b"  -> emitted "a)b: v\n"   -> UNPARSEABLE (InvalidKey)

So the accurate refusal list for this issue is exactly four classes:

1. "" — empty key
2. "##note" — key starting with the comment marker
3. edge whitespace — " k" / "k " (pending the [0.7] Key trimming — parser strips all Unicode whitespace, § 4 mandates ASCII only #6 decision on which whitespace set counts)
4. keys containing ( or ) — no § 3.7 escape exists for either

Not line breaks, and not , { } [ ] . : \ — all seven of those are representable and round-trip today.

The issue body's own table still lists "k\nx" under unrepresentable; that row is now stale and should be dropped when this is implemented.

[chappihappymeal]

Heads-up so this doesn't silently block on me: I'm heading off to other projects, so I won't be bringing the 0.7 PR for this issue myself after all.

Everything needed is already in place, though. The full implementation with the 9 tests lives in PR #4's history at a78b1e4 (the seam is check_key_representable in src/render/helpers.rs), and your two comments above already define the corrected refusal list — the check just needs trimming to the four classes ("", leading ##, edge whitespace pending #6, and ( / ) keys) once 0.7 picks up main.

It's been a genuine pleasure — three releases in five days, every report independently verified before landing, and a clean split negotiated instead of a rewrite. Best upstream experience I've had. Hope the reports were useful; if you ever want a hand or a second pair of eyes on the format, I'm reachable on Telegram: @golang_backend1.

[PHPCraftdream]

Thank you — genuinely, for all of it. The reports were more than useful; several of them changed decisions in this project for the better (the notation-boundaries fix, the strict-mode invariant, this very refusal list). Independent, careful, and generous with the detail — that's rare.

Appreciate you leaving the exact seam (check_key_representable, a78b1e4) so this doesn't stall — will pick it up from there for 0.7.

Wishing you well with what's next. The door's always open here — come back anytime, for this issue or anything else. Thank you again.