← Back to journal

The Unicode Bug Hiding in a Source Span

Why Kalu binds bundle edits to UTF-8 byte ranges rather than JavaScript string length.

Evidence basisKalu, Korpus, and frozen Ushman source/docs snapshot reviewed September 17, 2026; no new runtime qualification performed
DisclosureEngineering or methodology note based on a September 17, 2026 snapshot. Source-level behavior is not a public availability or universal compatibility claim. Any scenarios are illustrative, not customer outcomes.
Published by Kalu KodeRequest a KodeBack assessment →

Scope: Engineering or methodology note based on a September 17, 2026 snapshot. Source-level behavior is not a public availability or universal compatibility claim. Any scenarios are illustrative, not customer outcomes.

A source span looks simple: start here, end there. The simplicity disappears when one component counts bytes and another counts JavaScript string positions.

Kalu’s bundle-isolation boundary uses half-open UTF-8 byte ranges. JavaScript string indices are UTF-16 code units. Those coordinate systems can agree for an ASCII-only example and disagree as soon as non-ASCII text appears before the selected declaration.

A tiny comment can move the wrong boundary

Imagine a synthetic bundle with a non-ASCII comment before a function selected for replacement. The function’s logical position in the syntax tree is unchanged, but the byte count before it differs from the string-index count. Passing one coordinate system as the other can carve the wrong bytes.

That is why a source-length shortcut is unsafe. The engine must derive coordinates from the actual encoded source or a dedicated coordinate map, and the later verifier must use the same declared convention.

Bind the coordinates to the bytes

A span is meaningful only for a specific source identity. If the source changes after analysis, even perfectly calculated offsets may refer to a different region. The rewrite evidence therefore needs input identity, output identity, path, and removal spans together.

Kalu’s span-carve verifier rederives the selection from source, reconstructs the expected output, and reparses it. A document hash alone is weaker than that source-bound verification. It can authenticate a report without establishing that the report describes a valid edit.

Keep the claim at the right layer

Correct coordinates do not prove package ownership or application equivalence. They establish one necessary condition for a bounded rewrite. Certification, transaction authority, and applicable behavior checks remain separate.

This is an implementation detail with a product consequence. An engineer should not need to avoid international text, comments, or string literals to keep a recovery tool’s edit boundaries meaningful. The coordinate contract should be explicit and independently checked.

The current source provides that contract for its supported shapes. It is not a guarantee that every JavaScript transformation is supported. It is a reminder that trustworthy recovery depends on small exact mechanisms as well as large architectural ideas. Sometimes the difference between an inspectable edit and a corrupted bundle is the unit used to count the characters before it.