<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
`Core.Encoding` defines a shared encoder contract and concrete encodings: **Utf8** (language default), **Hex**, and **Base64**. Invalid input returns `Result` errors; no silent replacement in v1.
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-CORE-PRIM-0020`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Design model](./articles/design-model/)
- [Verification and traceability](./articles/verification-and-traceability/)
<!-- /spec:generate:article-index -->

## Decision

v1 uses a Beskid `contract Encoder` with `EncodeToBytes` / `DecodeFromBytes` returning `Result`. No lossy decode in v1.

## Base contract — **ENC-001** … **ENC-009**

| ID | Requirement |
| --- | --- |
| **ENC-001** | Every encoding **must** expose `EncodeToBytes` and `DecodeFromBytes` returning `Result`. |
| **ENC-002** | Error type **must** be `EncodingError` with distinct variants. |
| **ENC-003** | Utf8 **must** be the language-default encoding for `string` boundaries. |
| **ENC-004** | Invalid UTF-8 decode **must** return `InvalidSequence`, not panic (corelib layer). |
| **ENC-005** | Encoders **must not** perform I/O. |
| **ENC-006** | Hex encode **must** use lowercase `a`–`f`. |
| **ENC-007** | Hex decode **must** accept case-insensitive pairs. |
| **ENC-008** | Base64 **must** use RFC 4648 standard alphabet with `=` padding on decode. |
| **ENC-009** | Module tier **must** be `@tier(standard)` for prelude re-export. |

## Per-encoding IDs

| ID | Requirement |
| --- | --- |
| **ENC-UTF8-001** | `EncodeToBytes` copies UTF-8 code units without re-encoding. |
| **ENC-UTF8-002** | `DecodeFromBytes` validates full buffer as UTF-8. |
| **ENC-HEX-001** | Odd-length hex input **must** error. |
| **ENC-B64-001** | Invalid padding or alphabet char **must** error. |

## Implementation anchors

- `compiler/corelib/packages/foundation/src/Core/Encoding/`

## Modules

| Module | Role |
| --- | --- |
| `Core.Encoding.EncodingError` | Shared error enum |
| `Core.Encoding.Contract` | `Encoder` contract with encode/decode |
| `Core.Encoding.Utf8` | Language-default UTF-8 |
| `Core.Encoding.Hex` | Hexadecimal |
| `Core.Encoding.Base64` | RFC 4648 standard Base64 |

Utf8 uses `__bytes_from_str` / `__str_from_bytes_utf8` at the runtime boundary. Hex and Base64 are pure Beskid over `Core.Bytes`.

| Requirement | Test anchor |
| --- | --- |
| **ENC-001**, **ENC-UTF8-001** | `EncodingUtf8Tests.bd` (source fixture; enable target when direct `__bytes_*` JIT resolves) |
| **ENC-HEX-001**, **ENC-B64-001** | `Core.Encoding.Hex` / `Base64` modules + `EncodingUtf8Tests.bd` hex round-trip |
| **ENC-005** | `System.FS` `ReadAllText` / `WriteAllText` UTF-8 paths |

Harness: `compiler/corelib/beskid_corelib/tests/corelib_tests/src/core/EncodingUtf8Tests.bd`