122 lines
8.7 KiB
Markdown
122 lines
8.7 KiB
Markdown
# 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.
|