design: define encoding representations and failure contract

[vycdev2]

Summary

Define the stable Phase K encoding API, byte/string representations, malformed-input behavior, and source/runtime boundary before expanding or extracting Jett's Rust-backed encoding implementation.

Source documentation

• docs/progress.md — Phase K, encoding
• docs/design.md — Hashing and encoding
• docs/design.md — Standard Library / Core Modules
• docs/architecture.md — Compiler Intrinsics vs Standard Library
• docs/architecture.md — Phase K: Full Standard Library

Current state

The checker hardcodes all six current operations as string -> string: encoding.base64_encode, base64_decode, hex_encode, hex_decode, url_encode, and url_decode. Their implementations are Rust interpreter dispatches; there is no compiler-shipped stdlib/encoding.jett.

Base64 currently uses the standard alphabet with padding, hex encoding emits lowercase digits, and URL encoding percent-escapes UTF-8 bytes with uppercase hex. Decoding can reject malformed Base64/hex or non-UTF-8 output at runtime even though the checked return type is an infallible string. URL decoding is lenient for malformed percent escapes and decodes + as space, while URL encoding emits %20 for spaces. Existing fixtures cover successful ASCII examples and round trips, but do not define byte-native inputs, malformed-input policy, Base64 variants, canonical decoding, or URL percent-versus-form semantics.

Scope

This issue includes:

• selecting string and/or bytes input and output types for Base64 and hex operations;
• defining fallible decoder signatures and stable error behavior for malformed input and decoded non-UTF-8 bytes;
• selecting supported Base64 alphabet/padding variants and canonical acceptance rules;
• defining hex casing and decoder acceptance rules;
• separating URL percent encoding from form encoding, including the +/space policy, component scope, UTF-8 handling, and malformed escape behavior;
• deciding which operations remain runtime kernels and which declarations or compositional wrappers belong in compiler-shipped .jett source;
• recording future HIR/MIR/native-backend requirements and dependency-ordered implementation/test slices.

This issue does not implement the selected policy, add compression or character-set conversion, redesign the bytes type, or create a general serialization framework.

Acceptance criteria

• A design artifact selects the public Base64, hex, and URL/form encoding surface.
• String/byte representations, decoder result types, malformed-input errors, UTF-8 behavior, casing, padding, and canonical acceptance are explicit.
• URL component scope and percent-versus-form +/space behavior are unambiguous.
• The permanent runtime-kernel versus source-defined stdlib boundary and future-backend requirements are recorded.
• Focused known-vector, Unicode, byte-native, malformed-input, and round-trip tests are identified for implementation slices.
• docs/design.md, docs/architecture.md, and docs/progress.md are aligned with the selected policy.

Dependencies / open questions

Coordinate compiler-shipped module origin and import spelling with #3. Reuse the existing bytes representation where possible without absorbing broader byte API design. Future HIR/MIR/native lowering should preserve the selected contract through #20 and #22, but those stages are not prerequisites for the interpreter-facing design decision.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.