niklas/amduat-api
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat-api/tier1/fps.md
Carl Niklas Rydberg 75a9af3065 add some more specs
2026-01-17 00:07:10 +01:00

8.7 KiB
Raw Blame History

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.
{"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.