amduat-api/tier1/fps.md

# AMDUAT-FPS/1 — Functional Primitive Surface
Status: Draft | Owner: Architecture | SoT: Yes | Linked Phase: PH02 Aaru
Version: 0.4.4 | Last Updated: 2025-11-30
Tags: [fps, primitives, kheper]

identity_authority: amduat.programme
lineage_id: L-PENDING-FPS1
doc_code: AMDUAT-FPS/1
code_status: tentative
doc_code_aliases: []

location: /amduat/tier1/fps.md
surface: developer
internal_revision: 5
provenance_mode: full

## Scope
FPS/1 defines the deterministic primitive layer that upgrades the Kheper CAS from
storage-only semantics to byte-level transformations. The surface governs
reproducible implementations of `put`, `get`, `slice`, `concatenate`, `reverse`,
and `splice` across C and Python libraries, backed by COR/1 artifacts and
single-CID outputs. Deliverables include the normative primitive definitions,
validation matrices, and the descriptor model that treats primitive compositions
as addressable data.

## Library Deliverables

* Canonical C implementation exported under `/amduat/src/c/` within the Kheper
  reference tree and stored as COR/1 objects.
* Canonical Python implementation exported under `/amduat/src/python/` with
  parity harness alignment.
* Deterministic test vectors recorded in `/amduat/tier1/testvectors/ph02-baseline.md`.
* Traceability coverage maintained in `/amduat/tier1/ph02-traceability.md` linking
  Tier-0/Tier-1 requirements, ADR-015, and evidence.

## Governance Hooks

* FPS/1 evolutions require additive ADRs; breaking semantics mandate a future
  FPS/2 designation.
* Implementations SHALL emit ADR-006 symbolic errors when primitives reject
  invalid inputs.
* Phase Pack updates in `/amduat/phases/ph02/phase-pack.md` capture hygiene and
  evidence deltas for this surface.

## Primitive Requirements

Each requirement is normative, uniquely identified, and captured in the trace matrix
(`/amduat/tier1/ph02-traceability.md`).  Verification references use manifest
anchors (see §Deterministic Fixture Strategy) and language-specific harnesses.

| ID | Statement | Primary Verification | Notes |
| -- | --------- | -------------------- | ----- |
| **REQ-FPS-001 — PUT Determinism** | Given canonical payload `P` and target CID `C`, `put(P, C)` **SHALL** persist byte-identical artifacts in the C and Python reference libraries, emitting `C` as the sole identifier with no auxiliary state. | Harness replay of `manifest://ph02/fps-baseline.jsonl#PUT-001` using both language adapters, cross-checking CID stability. | Negative coverage uses `PUT-ERR-MISMATCH` to prove CID drift is rejected. |
| **REQ-FPS-002 — GET Fidelity** | `get(C)` **SHALL** return canonical payload `P` without mutation and **SHALL** surface ADR-006 `ERR_NOT_FOUND` when `C` is absent. | Fixture pair `GET-001` (positive) and `GET-ERR-NOT-FOUND` (negative) verifying payload integrity and error symbol parity. | Reuses storage evidence from PH01 to confirm no regression to CAS semantics. |
| **REQ-FPS-003 — SLICE Bounds** | `slice(C, start, length)` **SHALL** emit subsequence `P[start:start+length)` and **SHALL** raise ADR-006 `ERR_RANGE` for out-of-bounds arguments. | Manifests `SLICE-001` and `SLICE-ERR-BOUNDS` executed with deterministic byte fixtures and boundary fuzz set. | Start/length expressed as integers in manifest `inputs` for portability across FFI layers. |
| **REQ-FPS-004 — CONCAT Closure** | `concatenate(C_a, C_b)` **SHALL** deterministically construct payload `P_ab` whose CID is reproducible across implementations and **SHALL** persist provenance pair `(C_a, C_b)` inside manifest metadata. | Vector `CONCAT-001` plus provenance hash assertions stored alongside manifest verification proofs. | CID determinism confirmed by storing computed values under `expected.cid` and diffing harness logs. |
| **REQ-FPS-005 — REVERSE Involution** | `reverse(C)` **SHALL** produce payload `P_rev` such that `reverse(reverse(C))` returns the original payload; error semantics mirror `REQ-FPS-002`. | Sequence `REVERSE-001` followed by replay entry `REVERSE-INVOLUTION` to confirm involution property and rejection parity. | Harness MUST compare digests before/after double reversal. |
| **REQ-FPS-006 — SPLICE Integrity** | `splice(C, start, length, insert)` **SHALL** excise the specified range and insert payload `insert`, yielding deterministic CIDs and ADR-006 `ERR_RANGE` for invalid spans. | Fixtures `SPLICE-001` and `SPLICE-ERR-RANGE` verifying deterministic outputs and boundary enforcement. | Insert payloads reference canonical fixture `cid:fps-insert-a` for reproducibility. |

## Rejection Matrix (ADR-006 Alignment)

Baseline error semantics remain governed by ADR-015 (`/amduat/arc/adrs/adr-015.md`) and reuse the symbolic catalogue ratified during the PH02 charter freeze.

| Error Code | Trigger | Guaranteed Behavior |
| ---------- | ------- | ------------------- |
| `ERR_OVERFLOW` | Computed offsets or concatenated payload lengths exceed manifest-declared bounds, indicating arithmetic overflow risk. | Reject operation without mutating storage; emit ADR-006 symbol and record provenance in harness logs. |
| `ERR_INSERT_MISMATCH` | `splice` insert payload CID/digest disagrees with manifest expectation or language harness payload length. | Abort splice, preserve original payload, and return ADR-006 error while logging mismatch context. |
| `ERR_PAYLOAD_EMPTY` | Primitives receive zero-length payloads where manifest requires canonical bytes (e.g., `put`, `concatenate`). | Deny operation, return ADR-006 error, and require harness to surface empty-payload rejection evidence. |
| `ERR_EXEC_TIMEOUT` | Executor exceeded deterministic time envelope (Maat’s Balance breach). | Abort primitive execution, emit ADR-006 error, and log timing evidence under `/logs/ph03/evidence/`. |

> Verified under PH02.5 Bridge Hygiene pass (2025-11-02). No semantic changes.

## Deterministic Fixture Strategy

Fixture manifests SHALL be defined once and consumed by both language harnesses.

* **Format:** JSON Lines (`.jsonl`) entries containing `id`, `primitive`, `inputs`,
  `expected`, optional `error`, and optional `notes` for provenance commentary.
  Inputs capture CIDs, literal payload ranges, and primitive arguments.
* **Shared payload handles:** `cid:fps-baseline` references the canonical byte
  fixture; derivative payloads (e.g., `cid:fps-concat-ab`, `cid:fps-insert-a`)
  record parent CID lineage to preserve traceability.
* **Language hooks:** Harness adapters attach metadata without mutating the core
  manifest.  C harness annotations live in sibling YAML files; Python adapters
  ingest JSONL directly.
* **Negative vectors:** Each primitive includes at least one `error` entry
  mirroring ADR-006 error codes (`ERR_NOT_FOUND`, `ERR_RANGE`, etc.) to demonstrate
  rejection parity.
* **Integrity guards:** Manifest commits SHALL capture SHA-256 hashes in the
  traceability register and Phase Pack to detect drift across harness executions.

```json
{"id": "SLICE-001", "primitive": "slice", "inputs": {"cid": "cid:fps-baseline", "start": 4, "length": 8}, "expected": {"cid": "cid:fps-slice-4-8", "digest": "sha256:..."}}
{"id": "SLICE-ERR-BOUNDS", "primitive": "slice", "inputs": {"cid": "cid:fps-baseline", "start": 4096, "length": 32}, "error": {"code": "ERR_RANGE"}, "notes": "Verifies ADR-006 range guard"}
```

---

## PH03 Rejection Matrix

New ADR-016/017 validation surfaces introduce additional symbolic errors consumed by FPS/1 harnesses when verifying composite descriptors:

| Error Code | Trigger | Linked Surface |
| ---------- | ------- | --------------- |
| `ERR_PCB_ARITY_MISMATCH` | FCS/1 descriptor `arity` disagrees with PCB1 slot manifest count during harness validation. | FCS/1 Descriptor Checks |
| `ERR_FCS_CYCLE_DETECTED` | Composition graph traversal detects a cycle or self-reference between nested FCS/1 descriptors. | FCS/1 Graph Validator |

Harness evidence MUST demonstrate deterministic rejection for these errors alongside existing ADR-006 matrices.

---

## Document History

* **0.1.0 (2025-10-27):** Initial skeleton establishing FPS/1 scope, library deliverables, and governance hooks under PH02 Aaru.
* **0.2.0 (2025-10-31):** Added REQ-FPS-001..006 and fixture governance.
* **0.3.0 (2025-11-01):** Refined verification matrix and fixture governance.
* **0.4.0 (2025-11-01):** Added ADR-006 rejection matrix covering ERR_OVERFLOW, ERR_INSERT_MISMATCH, and ERR_PAYLOAD_EMPTY.
* **0.4.1 (2025-11-02):** Cross-linked ADR-015 for rejection governance and recorded PH02.5 bridge hygiene verification note (no semantic deltas).
* **0.4.2 (2025-11-15):** Documented PH03 rejection matrix for ERR_PCB_ARITY_MISMATCH and ERR_FCS_CYCLE_DETECTED.
* **0.4.3 (2025-11-19):** Added ERR_EXEC_TIMEOUT to rejection matrix to enforce deterministic timing evidence.
* **0.4.4 (2025-11-30):** Added DOCID header (pending lineage), keeping FPS/1 scope unchanged.