138 lines
2.5 KiB
Markdown
138 lines
2.5 KiB
Markdown
|
# FPS/1 — Functional Primitive Surface
|
||
|
|
|
||
|
|
Status: Approved
|
||
|
|
Owner: Architecture
|
||
|
|
Version: 1.0.0
|
||
|
|
SoT: Yes
|
||
|
|
Last Updated: 2026-02-21
|
||
|
|
Tags: [primitives, determinism, bytes]
|
||
|
|
|
||
|
|
**Document ID:** `FPS/1`
|
||
|
|
**Layer:** L1 — Deterministic functional primitives over payload bytes
|
||
|
|
|
||
|
|
**Depends on (normative):**
|
||
|
|
|
||
|
|
* `ASL/1-CORE` — `Artifact`, `Reference`, hash identity
|
||
|
|
* `HASH/ASL1` — hash family registry
|
||
|
|
* `ADR-006` — deterministic error semantics
|
||
|
|
* `ADR-015` — CAS rejection governance (alignment)
|
||
|
|
|
||
|
|
**Informative references:**
|
||
|
|
|
||
|
|
* `SRS` §12 — Functional Primitive Surface summary
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 0. Conventions
|
||
|
|
|
||
|
|
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are
|
||
|
|
to be interpreted as in RFC 2119.
|
||
|
|
|
||
|
|
FPS/1 defines **pure, deterministic** operations over canonical byte payloads.
|
||
|
|
The primitives are functional: identical inputs MUST produce identical outputs.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. CID Derivation
|
||
|
|
|
||
|
|
All primitives produce exactly one output payload and one CID.
|
||
|
|
|
||
|
|
The CID for a payload is derived as:
|
||
|
|
|
||
|
|
```
|
||
|
|
cid = algo_id || H("CAS:OBJ\0" || payload)
|
||
|
|
```
|
||
|
|
|
||
|
|
* `algo_id` is an `ASL/1-CORE` hash identifier.
|
||
|
|
* For v1, `algo_id` defaults to `HASH/ASL1` SHA-256.
|
||
|
|
* The domain separator **MUST** be exactly `"CAS:OBJ\0"`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Primitives (Normative)
|
||
|
|
|
||
|
|
### 2.1 put
|
||
|
|
|
||
|
|
```
|
||
|
|
put(payload_bytes) -> CID
|
||
|
|
```
|
||
|
|
|
||
|
|
Canonical write; identity only. Storage durability is out of scope here.
|
||
|
|
|
||
|
|
Errors: `ERR_IO_FAILURE`, `ERR_NORMALIZATION`
|
||
|
|
|
||
|
|
### 2.2 get
|
||
|
|
|
||
|
|
```
|
||
|
|
get(CID) -> payload_bytes
|
||
|
|
```
|
||
|
|
|
||
|
|
Fetch canonical bytes from a conformant store.
|
||
|
|
|
||
|
|
Errors: `ERR_CID_NOT_FOUND`
|
||
|
|
|
||
|
|
### 2.3 slice
|
||
|
|
|
||
|
|
```
|
||
|
|
slice(CID, offset, length) -> CID
|
||
|
|
```
|
||
|
|
|
||
|
|
Extract a contiguous byte range.
|
||
|
|
|
||
|
|
Errors: `ERR_SLICE_RANGE`
|
||
|
|
|
||
|
|
### 2.4 concatenate
|
||
|
|
|
||
|
|
```
|
||
|
|
concatenate([CID1, ..., CIDn]) -> CID
|
||
|
|
```
|
||
|
|
|
||
|
|
Join payloads in order.
|
||
|
|
|
||
|
|
Errors: `ERR_EMPTY_INPUTS`
|
||
|
|
|
||
|
|
### 2.5 reverse
|
||
|
|
|
||
|
|
```
|
||
|
|
reverse(CID, level) -> CID
|
||
|
|
```
|
||
|
|
|
||
|
|
Reverse payload order at a specified granularity:
|
||
|
|
|
||
|
|
* `bit` — reverse all bits in the payload
|
||
|
|
* `byte` — reverse byte order
|
||
|
|
* `word` — reverse 2-byte units
|
||
|
|
* `long` — reverse 4-byte units
|
||
|
|
|
||
|
|
Errors: `ERR_REV_ALIGNMENT`, `ERR_INVALID_LEVEL`
|
||
|
|
|
||
|
|
### 2.6 splice
|
||
|
|
|
||
|
|
```
|
||
|
|
splice(CID_a, offset, CID_b) -> CID
|
||
|
|
```
|
||
|
|
|
||
|
|
Insert payload `b` into `a` at `offset`.
|
||
|
|
|
||
|
|
Errors: `ERR_SPLICE_RANGE`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Determinism & Closure
|
||
|
|
|
||
|
|
* Identical inputs MUST produce identical outputs.
|
||
|
|
* Inputs are immutable.
|
||
|
|
* Outputs MUST be valid inputs to any FPS/1 primitive.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. Conformance Vectors
|
||
|
|
|
||
|
|
The canonical vectors live in:
|
||
|
|
|
||
|
|
```
|
||
|
|
/amduat/tests/fixtures/conformance/fps_1/
|
||
|
|
```
|
||
|
|
|
||
|
|
Vectors are required for each primitive and include output bytes and CID.
|