doc: Document known upstream kdl crate bugs
Assisted-by: Claude Opus 4.6 via pi
change xulsrxxkptoxmzuwkownwozuskqsrkxw
commit 1c5f493e5ca7e611cc29e37685e3103063fad1e0
author Alpha Chen <alpha@kejadlen.dev>
date
parent wsttsuzl
diff --git a/README.md b/README.md
index 822fdcc..c98fd66 100644
--- a/README.md
+++ b/README.md
@@ -170,6 +170,25 @@ just release X.Y.Z
 This bumps the version in `Cargo.toml`, commits, tags, and pushes. GitHub
 Actions then publishes the crate to crates.io and creates a GitHub release.
 
+## Potential upstream issues
+
+Property testing surfaced two roundtrip failures that appear to originate in
+the `kdl` crate (v6.5). These need further investigation to confirm root
+causes and determine whether to file upstream issues.
+
+**Control character escaping.** Strings containing certain control characters
+serialize to invalid KDL that the parser rejects. The kdl crate's `Display`
+for string values escapes `\\`, `"`, `\n`, `\r`, `\t`, `\b`, and `\f`, but
+appears to write other control characters verbatim. serde-kdl2 works around
+this by setting a custom `value_repr` with `\u{…}` escapes on affected
+entries. See `string_entry()` in `ser.rs`.
+
+**`i128::MIN` roundtrip failure.** Serializing `i128::MIN` produces valid KDL
+text, but the kdl parser rejects it. Possibly a sign-magnitude overflow during
+parsing (the absolute value of `i128::MIN` exceeds `i128::MAX`), but this
+hasn't been confirmed by reading the parser source. serde-kdl2 doesn't work
+around this — callers should avoid `i128::MIN` if roundtripping matters.
+
 ## AI Usage
 
 I built this crate with substantial help from Claude (Anthropic). The AI