<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
`Core.Bytes` provides allocation-explicit byte buffer operations on `u8[]` handles backed by `BeskidArray` and `__array_*` / `__bytes_*` runtime builtins. It **must not** call syscalls directly.
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- `compiler/corelib/packages/foundation/src/Core/Bytes/`
- `compiler/crates/beskid_runtime/src/builtins/arrays.rs`
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-CORE-PRIM-0010`); 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

`u8[]` with `__array_new(1, len)` is the canonical byte buffer. No separate `Bytes` heap type in v1.

## Verification anchors

`Core.Bytes.Slice.New`, `compiler/crates/beskid_runtime/src/builtins/arrays.rs`

## Normative requirements

| ID | Requirement |
| --- | --- |
| **BYTES-001** | `u8[]` **must** be the canonical byte buffer type; allocation uses `__array_new(1, len)`. |
| **BYTES-002** | Out-of-bounds index on `Get`/`Set` **must** trap (same policy as `string[index]`). |
| **BYTES-003** | `Core.Bytes` **must not** embed OS or syscall semantics. |
| **BYTES-004** | `Copy`, `Compare`, and `Fill` **must** be deterministic; allocation for `SubSlice` **must** be explicit. |
| **BYTES-005** | String ↔ bytes conversion **must** route through `Core.Encoding` (not ad-hoc UTF-8 in `Core.Bytes`). |
| **BYTES-006** | Empty buffers **must** be representable with length zero. |
| **BYTES-007** | `Len` **must** delegate to `__array_len`. |
| **BYTES-008** | Hot paths **may** use `__bytes_copy` / `__bytes_compare` builtins when registered. |
| **BYTES-009** | Module tier **must** be `@tier(standard)` for prelude re-export. |

## Edge cases

| Case | Behavior |
| --- | --- |
| Zero-length copy | No-op; returns without error |
| `SubSlice` past end | Clamps to buffer end per runtime contract |
| Null backing (test builds) | `Len` returns 0; indexed access traps |

## Implementation anchors

- `compiler/corelib/packages/foundation/src/Core/Bytes/`
- `compiler/corelib/beskid_corelib/tests/corelib_tests/src/core/BytesTests.bd`

## Module layout

| Module | Role |
| --- | --- |
| `Core.Bytes` | Re-export hub |
| `Core.Bytes.Errors` | `BytesError` variants |
| `Core.Bytes.Slice` | `Len`, `Get`, `Set`, `Copy`, `Compare`, `Fill`, `SubSlice`, `New` |
| `Core.Bytes.Convert` | Thin helpers delegating to `Core.Encoding.Utf8` |

## Layering

```mermaid
flowchart TB
  app[Application]
  bytes[Core.Bytes]
  array[Collections.Array]
  builtins[__array_* __bytes_*]
  app --> bytes --> array --> builtins
```

## Related topics

- [Contracts and edge cases](./contracts-and-edge-cases/)
- [Core.Encoding](/platform-spec/core-library/foundation-and-primitives/core-encoding/)

| Requirement | Test anchor |
| --- | --- |
| **BYTES-001**, **BYTES-007** | `BytesTests.bd` — `bytes_new_has_length` |
| **BYTES-003** | `BytesTests.bd` — `bytes_from_str_builtin_smoke` |
| **BYTES-002** | Runtime trap on OOB `__bytes_get` / `__bytes_set` (integration) |
| **BYTES-005** | `EncodingUtf8Tests.bd` — `utf8_from_str_builtin_round_trip` |

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