amduat/tier1/bytestore-1.md

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