84 lines
1.9 KiB
Markdown
84 lines
1.9 KiB
Markdown
# 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
|