# BYTESTORE/1 — ByteStore API and Persistence Boundary

Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2026-02-21
Tags: [bytestore, persistence, determinism]

**Document ID:** `BYTESTORE/1`
**Layer:** L0 — Persistence boundary (bytes only)

**Depends on (normative):**

* `DDS` §11 — ByteStore API & Persistence Discipline
* `SRS` FR-BS-001…005 — determinism + durability requirements
* `COR/1` — canonical envelope bytes
* `ICD/1` — `max_object_size` policy

**Informative references:**

* `ADR-030` — ByteStore Persistence Contract
* `AMDUAT_BYTESTORE` header — `vendor/amduat/include/amduat/bytestore.h`

---

## 1. Purpose

BYTESTORE/1 defines the **code-level API surface** for ByteStore and maps it to
the behavioural requirements already specified in DDS and SRS.

It does not define new semantics; DDS §11 remains the source of truth.

---

## 2. API Surface (Normative)

The following API signatures are required (see `amduat/bytestore.h`):

* `put(payload) -> cid`
* `put_stream(stream) -> cid`
* `import_cor(envelope) -> cid`
* `export_cor(cid) -> envelope`
* `get(cid) -> bytes`
* `stat(cid) -> {present, size}`
* `assert_area_isolation(public_root, secure_root)`

The error codes exposed by the header MUST map to ADR-006 lanes as specified in
DDS §11.7.

---

## 3. Deterministic Identity (Normative)

The CID derivation is fixed:

```
cid = algo_id || H("CAS:OBJ\0" || payload)
```

Implementations MUST use the exact domain separator and hash rules defined in
DDS §11.2 and SRS FR-BS-001.

---

## 4. Persistence Discipline (Normative)

All ByteStore writes MUST follow the fsync ladder from DDS §11.4 and enforce:

* `ICD/1 max_object_size`
* COR/1 import/export byte identity
* SA/PA isolation
* Streaming determinism

---

## 5. Non-Goals

BYTESTORE/1 does not define:

* Physical storage layout
* Replication protocols
* Transport or API gateways