niklas/amduat-api
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

add some more specs

Browse source
This commit is contained in:
Carl Niklas Rydberg 2026-01-17 00:07:10 +01:00
parent 08922ef22d
commit 75a9af3065
6 changed files with 1830 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

909
tier1/dds.md Normal file
View file

@ -0,0 +1,909 @@
# AMDUAT-DDS — Detailed Design Specification
Status: Approved | Owner: Niklas Rydberg | Version: 0.5.0 | Last Updated: 2025-11-11 | SoT: Yes
Tags: [design, cas, composition]
> **Note (scope):**
> This DDS covers **Phase 01 (Kheper CAS)** byte semantics and, where necessary, the canonical **binary encodings** for higher deterministic layers (FCS/1, PCB1, FER/1, FCT/1).
> **Behavioural semantics live in SRS.** This document governs the **bytes**.
**Normative references:** ADR-001, ADR-003, ADR-006, SRS.
---
## 1 – Content ID (CID)
**Rule.**
```
CID = algo_id || H("CAS:OBJ\0" || payload_bytes)
```
* `algo_id`: 1-byte or VARINT identifier (default `0x01` = SHA-256).
* `H`: selected hash over **exact payload bytes**.
* Domain separation prefix must be present verbatim: `"CAS:OBJ\0"`.
**Properties.**
* Deterministic: identical payload → identical CID.
* Implementation-independent (SRS NFR-001).
* Crypto-agile via `algo_id`.
**Errors.**
* `ERR_ALGO_UNSUPPORTED` when `algo_id` not registered.
* Empty payload is allowed and canonical.
---
## 2. Canonical Object Record (COR/1)
COR/1 is the **only** canonical import/export envelope for CAS objects. Exact bytes are consensus; on-disk layout is not.
### 2.1 Envelope Layout (exact bytes)
```
Header (7 bytes total):
MAGIC : 4 bytes = "CAS1" (0x43 0x41 0x53 0x31)
VERSION : 1 byte = 0x01
FLAGS : 1 byte = 0x00 (reserved; MUST be 0)
RSV : 1 byte = 0x00 (reserved; MUST be 0)
Body (strict TLV order; no padding):
0x10 algo_id (VARINT)
0x11 size (VARINT)
0x12 payload (BYTES; length == size)
```
**Notes**
* Fixed header invariants; any mismatch is rejection.
* No alignment/padding anywhere.
### 2.2 Tag Semantics
| Tag | Name | Type | Card. | Notes |
| ---: | ------- | ------ | ----: | ----------------------------------------------- |
| 0x10 | algo_id | VARINT | 1 | MUST equal algorithm used for the object’s CID. |
| 0x11 | size | VARINT | 1 | **Minimal VARINT**; MUST equal payload length. |
| 0x12 | payload | BYTES | 1 | Raw bytes; never normalized. |
### 2.3 Canonicalization Rules (strict)
1. **Order & uniqueness:** `0x10`, `0x11`, `0x12`, each exactly once.
2. **VARINTS:** Unsigned LEB128 **minimal** form only.
3. **BYTES:** `VARINT(len) || len bytes`, with `len == size`.
4. **No extras:** No unknown tags, no trailing bytes.
5. **Header invariants:** `MAGIC="CAS1"`, `VERSION=0x01`, `FLAGS=RSV=0x00`.
6. **Policy domain:** `size ≤ max_object_size` when enforced (ICD/1 §3).
7. **Raw byte semantics** (SRS FR-010).
### 2.4 Decoder Validation Algorithm (normative)
1. Validate header ⇒ else `ERR_COR_HEADER_INVALID`.
2. Read `0x10` minimal VARINT ⇒ else `ERR_COR_TAG_ORDER` / `ERR_VARINT_NON_MINIMAL`.
3. Read `0x11` minimal VARINT ⇒ same error rules.
4. Read `0x12` BYTES (length minimal VARINT) ⇒ else `ERR_VARINT_NON_MINIMAL`.
5. Enforce `size == len(payload)` ⇒ `ERR_COR_LENGTH_MISMATCH` on failure.
6. Ensure **no trailing bytes** ⇒ `ERR_TRAILING_BYTES`.
7. Recompute CID and compare ⇒ mismatch `ERR_CORRUPT_OBJECT`.
### 2.5 Consistency with CID (normative)
* **Export:** set `algo_id` to CID algorithm.
* **Import:** verify `algo_id` and hash component against expected CID.
* Mismatch ⇒ `ERR_ALGO_MISMATCH` / `ERR_CORRUPT_OBJECT`.
### 2.6 Round-Trip Identity
`import(COR/1) → export(CID)` MUST produce **byte-identical** envelope (SRS FR-005). Re-encoding is forbidden.
### 2.7 Rejection Matrix (normative)
| Violation | Example | Error |
| ------------------ | -------------------------------- | ------------------------- |
| Bad header | Wrong MAGIC/VERSION/FLAGS/RSV | `ERR_COR_HEADER_INVALID` |
| Unknown/extra tag | Any tag not 0x10/0x11/0x12 | `ERR_COR_UNKNOWN_TAG` |
| Out-of-order | `0x11` before `0x10` | `ERR_COR_TAG_ORDER` |
| Duplicate tag | Two `0x10` entries | `ERR_COR_DUPLICATE_TAG` |
| Non-minimal VARINT | Over-long algo/size/bytes length | `ERR_VARINT_NON_MINIMAL` |
| Length mismatch | `size != len(payload)` | `ERR_COR_LENGTH_MISMATCH` |
| Trailing bytes | Any bytes after payload | `ERR_TRAILING_BYTES` |
| Algo mismatch | `algo_id` conflicts with CID | `ERR_ALGO_MISMATCH` |
| Hash mismatch | Recomputed hash ≠ expected | `ERR_CORRUPT_OBJECT` |
---
## 3. Instance Descriptor (ICD/1)
ICD/1 publishes canonical instance configuration; its bytes are consensus.
### 3.1 Envelope
```
Header:
MAGIC : "ICD1"
VERSION : 0x01
TLV (strict order; minimal VARINTs; no duplicates):
0x20 algo_default (VARINT)
0x21 max_object_size (VARINT)
0x22 cor_version (VARINT) # 0x01 => COR/1 v1
0x23 gc_policy_id (VARINT; 0 if none)
0x24 impl_id (BYTES; optional build/impl descriptor CID)
```
### 3.2 Derived Identity
```
instance_id = SHA-256("CAS:ICD\0" || bytes(ICD/1))
```
**Rules:** Ordering/minimal VARINTs mirror COR/1. Exporters preserve canonical bytes; `instance_id` is stable.
---
## 4. Encodings
* **VARINT (unsigned LEB128)** — minimal form only; else `ERR_VARINT_NON_MINIMAL`.
* **BYTES** — `VARINT(length) || length bytes`.
* **Fixed-width integers** — big-endian if present.
* **No padding/alignment** in canonical encodings.
---
## 5. Algorithm Registry
**Default**
* `0x01` → SHA-256
**Reserved**
* `0x02` → SHA-512/256
* `0x03` → BLAKE3
**Policy**
* New entries require ADR + test vectors. Backward compatible by design.
---
## 6. Filesystem Considerations (Informative)
```
cas/
├─ sha256/
│ ├─ aa/.. # fan-out by CID prefix (implementation detail)
│ └─ ff/..
└─ amduat/
└─ <instance-id>/
├─ amduatcas
├─ sha256/.. # private runtime state; never a put() target
├─ interface/
│ └─ libamduatcas.current
├─ HEAD
└─ meta/
```
**Rule:** Public CAS API acts only on `cas/sha256/`. The per-instance subtree is private and MUST NOT receive `put()` writes.
---
## 7. Error Conditions & Higher-Layer Layouts (Normative)
### 7.1 COR/1 & ICD/1 Enforcement (codes)
* `ERR_COR_HEADER_INVALID`, `ERR_COR_UNKNOWN_TAG`, `ERR_COR_TAG_ORDER`, `ERR_COR_DUPLICATE_TAG`,
`ERR_COR_LENGTH_MISMATCH`, `ERR_VARINT_NON_MINIMAL`, `ERR_ALGO_UNSUPPORTED`,
`ERR_ALGO_MISMATCH`, `ERR_TRAILING_BYTES`, `ERR_CORRUPT_OBJECT`.
---
### 7.2 FCS/1 Descriptor Layout — v1-min (Normative)
> **Design principle:** *FCS/1 describes the deterministic execution recipe only.*
> Intent, roles, scope, authority, and registry policy are **not** encoded in FCS; they are captured at **certification time** in FCT/1.
Header: `MAGIC="FCS1" VERSION=0x01 FLAGS=RSV=0x00`
| Tag | Field | Type | Card. | Notes |
| ---: | ----------------- | ------ | ----: | ------------------------------------------ |
| 0x30 | `function_ptr` | CID | 1 | FPS/1 primitive or nested FCS/1 descriptor |
| 0x31 | `parameter_block` | CID | 1 | CID of PCB1 parameter block |
| 0x32 | `arity` | VARINT | 1 | Expected parameter slots |
**Validation rules**
1. Strict TLV order; duplicates/out-of-order → `ERR_FCS_TAG_ORDER`.
2. `parameter_block` MUST be valid PCB1 → `ERR_FCS_PARAMETER_FORMAT`.
3. `arity` MUST match slot count → `ERR_PCB_ARITY_MISMATCH`.
4. Descriptor graph MUST be acyclic → `ERR_FCS_CYCLE_DETECTED`.
5. **Any unknown or legacy governance tag** (`registry_policy 0x33`, `intent_vector 0x34`, `provenance_edge 0x35`, `notes 0x36`, or unregistered fields) → `ERR_FCS_UNKNOWN_TAG`. Such tags MUST never be tolerated in canonical streams.
---
### 7.3 PCB1 Parameter Blocks (Normative)
PCB1 payloads are COR/1 envelopes with header `MAGIC="PCB1"`, `VERSION=0x01`, `FLAGS=RSV=0x00`.
| Tag | Field | Type | Notes |
| ---: | --------------- | ----- | ----------------------------------------------------- |
| 0x50 | `slot_manifest` | BCF/1 | Canonical slot descriptors `{index,name,type,digest}` |
| 0x51 | `slot_data` | BYTES | Packed slot bytes respecting manifest order |
**Rules:**
Slots appear in ascending `index`. Numeric slots default to `0` when omitted.
Digest mismatches ⇒ `ERR_PCB_DIGEST_MISMATCH`. Non-deterministic ordering ⇒ `ERR_PCB_MANIFEST_ORDER`.
Arity mismatch vs FCS/1 ⇒ `ERR_PCB_ARITY_MISMATCH`.
---
### 7.4 **FER/1 Receipt Layout (Normative)**
FER/1 receipts reuse COR/1 framing with header `"FER1"` and are byte-deterministic.
**Strict TLV order (no padding):**
| Tag | Field | Type | Cardinality | Notes |
| ---- | --------------------- | ----------- | ----------- | ----- |
| 0x40 | `function_cid` | CID | 1 | Evaluated FCS/1 descriptor (must decode to v1-min). |
| 0x41 | `input_manifest` | CID | 1 | MUST decode to GS/1 BCF/1 set list (deduped, byte-lexicographic). |
| 0x42 | `environment` | CID | 1 | ICD/1 snapshot or PH03 environment capsule. |
| 0x43 | `evaluator_id` | BYTES | 1 | Stable evaluator identity (DID/descriptor CID). |
| 0x44 | `executor_set` | BCF/1 map | 1 | Map of executors → impl metadata (language/version/build); keys sorted. |
| 0x4F | `executor_fingerprint`| CID | 0–1 | SBOM/attestation CID feeding `run_id`; REQUIRED when `run_id` present. |
| 0x45 | `output_cid` | CID | 1 | Canonical output CID (single-output invariant). |
| 0x46 | `parity_vector` | BCF/1 list | 1 | Sorted by executor key; each entry carries `{executor, output, digest, sbom_cid}`. |
| 0x47 | `logs` | LIST<BCF/1> | 0–1 | Typed log capsules (`kind`, `cid`, `sha256`). |
| 0x51 | `determinism_level` | ENUM | 0–1 | `"D1_bit_exact"` (default) or `"D2_numeric_stable"`. |
| 0x50 | `rng_seed` | BYTES | 0–1 | 0–32 byte seed REQUIRED when determinism ≠ D1. |
| 0x52 | `limits` | BCF/1 map | 0–1 | Resource envelope (`cpu_ms`, `wall_ms`, `max_rss_kib`, `io_reads`, `io_writes`). |
| 0x48 | `started_at` | UINT64 | 1 | Epoch seconds (FR-020 start bound). |
| 0x49 | `completed_at` | UINT64 | 1 | Epoch seconds ≥ `started_at`. |
| 0x53 | `parent` | CID | 0–1 | Optional lineage pointer for follow-up runs. |
| 0x4A | `context` | BCF/1 map | 0–1 | Optional scheduling hooks (WT/1 ticket, TA/1 branch tip, notes ref). |
| 0x4B | `witnesses` | BCF/1 list | 0–1 | Optional observer descriptors / co-signers. |
| 0x4E | `run_id` | BYTES[32] | 0–1 | Deterministic dedup anchor (`H("AMDUAT:RUN\0" || function || manifest || env || fingerprint)`). |
| 0x4C | `signature` | BCF/1 map | 1 | Primary Ed25519 signature over `H("AMDUAT:FER\0" || canonical bytes)`. |
| 0x4D | `signature_ext` | BCF/1 list | 0–1 | Reserved slot for multi-sig / threshold proofs (future). |
**Validation:**
1. TLV order strict; unknown tags ⇒ `ERR_FER_TAG_ORDER` / `ERR_FER_UNKNOWN_TAG`.
2. `function_cid` must decode to valid FCS/1 ⇒ `ERR_FER_FUNCTION_MISMATCH` otherwise.
3. `input_manifest` MUST decode to GS/1 set list (deduped + byte-lexicographic). Violations ⇒ `ERR_FER_INPUT_MANIFEST_SHAPE`.
4. `executor_set` keys MUST be byte-lexicographic and align with `parity_vector` entries. Ordering mismatches ⇒ `ERR_IMPL_PARITY_ORDER`; missing executors or divergent outputs ⇒ `ERR_IMPL_PARITY`.
5. Each parity entry MUST declare `sbom_cid` referencing the executor’s mini-SBOM CID.
6. `determinism_level` defaults to `D1_bit_exact`; when set to any other value a 0–32 byte `rng_seed` is REQUIRED ⇒ `ERR_FER_RNG_REQUIRED`.
7. `limits` (when present) MUST supply non-negative integers for `cpu_ms`, `wall_ms`, `max_rss_kib`, `io_reads`, `io_writes`.
8. `logs` (when present) MUST contain objects with `kind ∈ {stderr, stdout, metrics, trace}`, `cid`, and `sha256` (both 32-byte hex strings).
9. `run_id` (when present) MUST equal `H("AMDUAT:RUN\0" || function_cid || manifest_cid || environment_cid || executor_fingerprint)`; missing fingerprint ⇒ `ERR_FER_UNKNOWN_TAG`.
10. `completed_at < started_at` ⇒ `ERR_FER_TIMESTAMP` (FR-020 envelope enforcement).
11. Signatures MUST verify against `H("AMDUAT:FER\0" || canonical bytes)` ⇒ failure ⇒ `ERR_FER_SIGNATURE`.
> **Manifest note:** `input_manifest` bytes MUST be the GS/1 canonical list; ingestion MUST reject producer-specific ordering.
> **Log capsule note:** `logs` entries bind `kind`, `cid`, and `sha256` together to avoid stdout/stderr hash confusion.
> **Dedup note:** `run_id` enables idempotent FER ingestion across registries while keeping the FER CID authoritative.
> **Provenance note:** FER/1 remains the exclusive home for run-time provenance and parity outcomes; governance stays in FCT/1.
> **Graph note:** Ingestors emit `realizes`, `produced_by`, `consumed_by`, and (optionally) `fulfills` edges based solely on FER content.
---
### 7.5 **FCT/1 Transaction Envelope (Normative)**
> **Design principle:** *FCT/1 is the canonical home for **intent**, **domain scope**, **roles/authority**, and **policy snapshot*** captured at certification/publication time.
FCT/1 serializes as ADR-003 BCF/1 map with canonical keys:
| Key | Type | Notes |
| --------------------- | ----------- | ------------------------------------------------------- |
| `fct.version` | UINT8 | MUST be `1` |
| `fct.registry_policy` | UINT8 | Publication policy snapshot (0=Open,1=Curated,2=Locked) |
| `fct.function` | CID | Certified FCS/1 descriptor |
| `fct.receipts` | LIST<CID> | One or more FER/1 CIDs |
| `fct.authority_role` | ENUM | ADR-010C role |
| `fct.domain_scope` | ENUM | ADR-010B scope |
| `fct.intent` | SET<ENUM> | ADR-010 intents |
| `fct.constraints` | LIST<BCF/1> | Optional constraint set |
| `fct.attestations` | LIST<BYTES> | Required when policy ≠ Open |
| `fct.timestamp` | UINT64 | Epoch seconds |
| `fct.publication` | CID | Optional ADR-007 digest |
**Validation:**
1. All receipts reference the same `function_cid` ⇒ else `ERR_FCT_RECEIPT_MISMATCH`.
2. If `registry_policy ≠ 0` then `attestations` **required** ⇒ `ERR_FCT_ATTESTATION_REQUIRED`.
3. All signatures/attestations verify ⇒ `ERR_FCT_SIGNATURE` on failure.
4. Receipt timestamps must be monotonic ⇒ `ERR_FCT_TIMESTAMP`.
---
### 7.6 FPD/1 Publication Digest (Normative)
> **Design principle:** *Federation publishes exactly one deterministic digest per event (ADR-007, SRS FR-022).*
FPD/1 serializes as an ADR-003 BCF/1 map with canonical keys:
| Key | Type | Notes |
| --------------- | ---------- | --------------------------------------------------------------------- |
| `fpd.version` | UINT8 | MUST be `1`. |
| `fpd.members` | LIST<CID> | Deterministic, byte-lexicographic list of member artefact CIDs. |
| `fpd.parent` | CID (opt) | Previous FPD/1 digest for the domain publication chain (or `null`). |
| `fpd.timestamp` | UINT64 | Epoch seconds aligned with `fct.timestamp` monotonic ordering. |
| `fpd.digest` | CID | Canonical digest over `{FCT/1 bytes, FER/1 receipts, governance edges}`. |
**Construction:**
1. Normalize and sign the FCT/1 record (per §7.5) writing canonical bytes to the payload area (PA).
2. Collect referenced FER/1 receipts and governance edges (`certifies`, `attests`, `publishes`) as canonical byte arrays.
3. Build `fpd.members` as the byte-lexicographic list of CIDs for the certified FCT/1 record, every FER/1 receipt, and the edge batch capsule.
4. Hash the concatenated canonical payloads using the federation digest algorithm (default `CIDv1/BCF`). Persist the resulting bytes and record the CID in `fpd.digest`.
5. If a prior publication exists, set `fpd.parent` to the previous digest CID; otherwise omit.
6. Emit the FPD/1 map, persist alongside the FCT/1 payload under `/logs/ph03/evidence/fct/`, and update `fct.publication` with the FPD/1 CID.
**Validation:**
* `fpd.members` MUST include exactly one FCT/1 CID and the full set of FER/1 receipt CIDs referenced by that transaction.
* Recomputing the digest from the persisted canonical payloads MUST yield `fpd.digest`; mismatches ⇒ `ERR_FPD_DIGEST` (registered under ADR-006).
* `fpd.timestamp` MUST be ≥ the largest FER/1 `completed_at` and ≥ the prior `fpd.timestamp` when `fpd.parent` is present ⇒ violations raise `ERR_FPD_TIMESTAMP`.
* Graph emitters MUST log governance edges via `lib/g1-emitter/` using the canonical digests referenced above.
> **Graph note:** Publication surfaces emit `publishes(fct,fpd)` edges binding certification state to digest lineage for PH04 FLS/1 integration.
### 7.7 Error Surface Registration (consolidated)
All FCS/1, PCB1, FER/1, and FCT/1 errors map to ADR-006.
Additions since v0.3.0:
| Code | Meaning |
| --------------------- | -------------------------------------------------------------------------------------- |
| `ERR_FCS_UNKNOWN_TAG` | Descriptor contained a tag outside the v1-min set (`0x30-0x32`). Rejected per ADR-006. |
| `ERR_EXEC_TIMEOUT` | Executor exceeded deterministic time envelope (Maat’s Balance). |
| `ERR_IMPL_PARITY` | Executor outputs/parity metadata diverged (missing executor, mismatched `output_cid`). |
| `ERR_IMPL_PARITY_ORDER` | Parity vector ordering did not match the canonical executor ordering. |
| `ERR_FER_UNKNOWN_TAG` | FER/1 payload contained an unknown tag or cardinality violation. |
| `ERR_FER_INPUT_MANIFEST_SHAPE` | `input_manifest` failed GS/1 set decoding (not deduped or unsorted). |
| `ERR_FER_RNG_REQUIRED` | `determinism_level` demanded an `rng_seed` but none was provided. |
| `ERR_FPD_DIGEST` | Recomputed federation digest did not match `fpd.digest` (non-deterministic publication). |
| `ERR_FPD_TIMESTAMP` | Publication timestamp regressed relative to receipts or parent digest. |
| `ERR_FPD_PARENT_REQUIRED` | Policy-enforced lineage expected `fpd.parent` but none was provided. |
| `ERR_FPD_MEMBER_DUP` | Duplicate member CID detected in the canonical set ordering. |
| `ERR_WT_UNKNOWN_KEY` | WT/1 map contained a key outside the v1-min schema. |
| `ERR_WT_VERSION_UNSUPPORTED` | `wt.version` not equal to `1`. |
| `ERR_WT_INTENT_EMPTY` | `wt.intent` list empty. |
| `ERR_WT_INTENT_DUP` | Duplicate ADR-010 intents detected in `wt.intent`. |
| `ERR_WT_TIMESTAMP` | `wt.timestamp` regressed relative to the previous ticket from the same author. |
| `ERR_WT_SIGNATURE` | Signature validation over `"AMDUAT:WT\0"` failed. |
| `ERR_WT_KEY_UNBOUND` | Declared `wt.pubkey` is not authorized for `wt.author` via the predicate registry. |
| `ERR_WT_INTENT_UNREGISTERED` | `wt.intent` entry not registered in ADR-010 predicate registry. |
| `ERR_WT_SCOPE_UNAUTHORIZED` | Router policy rejected the declared domain scope. |
| `ERR_WT_PARENT_UNKNOWN` | Optional `wt.parent` reference could not be resolved. |
| `ERR_WT_PARENT_REQUIRED` | Policy required `wt.parent` but the field was omitted. |
| `ERR_SOS_UNKNOWN_KEY` | SOS/1 map contained a key outside the v1-min schema. |
| `ERR_SOS_VERSION_UNSUPPORTED` | `sos.version` not equal to `1`. |
| `ERR_SOS_PREDICATE_UNREGISTERED` | Overlay predicate not registered in the CRS predicate registry. |
| `ERR_SOS_POLICY_INCOMPATIBLE` | `sos.policy` outside `{0,1,2}` or disallowed for the deployment lane. |
| `ERR_SOS_SIGNATURE_INVALID` | Signature validation over `"AMDUAT:SOS\0"` failed. |
| `ERR_SOS_COMPAT_EVIDENCE_REQUIRED` | Compat overlays missing MPR/1 + IER/1 references. |
| `ERR_SOS_TIMESTAMP_REGRESSION` | Overlay timestamp regressed relative to policy baseline. |
### 7.8 FLS/1 and CRS/1 Byte Semantics
Phase 04 establishes deterministic linkage between FLS/1 envelopes and CRS/1 concept graphs. ADR-018 governs the linkage envelope; ADR-020 governs concept and relation payloads. CI harnesses (`tools/ci/run_vectors.py`, `tools/ci/gs_snapshot.py`) provide conformance evidence.
#### 7.8.1 FLS/1 Envelope TLVs (Draft)
> **Scope:** Draft wire image aligned with ADR-018 v0.5.0. Stewardship will finalize signature semantics alongside multi-surface publication work.
| Tag | Field | Type | Card. | Notes |
| ------ | -------------------- | ------ | ----- | ----- |
| `0x60` | `source_cid` | CID | 1 | Deterministic sender artefact/surface. |
| `0x61` | `target_cid` | CID | 1 | Deterministic recipient artefact/surface. |
| `0x62` | `payload_cid` | CID | 1 | Content payload (COR/1 capsule, CRS/1 concept, or CRR/1 relation). |
| `0x63` | `routing_policy_cid` | CID | 0-1 | Optional deterministic policy capsule. |
| `0x64` | `timestamp` | UINT64 | 0-1 | Optional bounded timing evidence (big-endian). |
| `0x65` | `signature` | BYTES | 0-1 | Optional Ed25519 signature with `"AMDUAT:FLS\0"` domain separator. |
**Envelope rules (draft):**
* Header MUST present `MAGIC="FLS1"`, `VERSION=0x01`, and zeroed `FLAGS/RSV` bytes.
* TLVs MUST appear in strictly increasing tag order. Duplicate tags ⇒ `ERR_FLS_DUPLICATE_TAG`; reordering ⇒ `ERR_FLS_TAG_ORDER`.
* Unknown tags are rejected until ADR updates extend this table (`ERR_FLS_UNKNOWN_TAG`).
* CID TLVs MUST present 32-byte payloads aligned with ADR-001 ⇒ `ERR_FLS_CID_LENGTH`.
* `timestamp` MUST be exactly eight bytes (UINT64, network byte order) ⇒ `ERR_FLS_TIMESTAMP_LENGTH`.
* `signature` MUST start with `"AMDUAT:FLS\0"` and carry a 64-byte Ed25519 signature ⇒ `ERR_FLS_SIGNATURE_DOMAIN` / `ERR_FLS_SIGNATURE_LENGTH`; failing Ed25519 verification raises `ERR_FLS_SIGNATURE`.
* When supplied, CRS payload bytes MUST hash to the declared `payload_cid` using `SHA-256("CAS:OBJ\0" || payload)` ⇒ `ERR_FLS_PAYLOAD_CID_MISMATCH`.
* CRS payload headers MUST match `CRS1` (concept) or `CRR1` (relation) when linkage metadata declares the type ⇒ `ERR_FLS_PAYLOAD_KIND`.
* Payloads MAY be CRS/1 concepts or CRR/1 relations; FLS/1 envelopes never mutate CRS graphs.
#### 7.8.2 CRS/1 Concept & Relation TLVs (Normative)
> **Scope:** Deterministic CRS/1 byte layout as ratified by ADR-020 v1.1.0. All TLVs
> use single-byte tags + single-byte lengths with fixed 32-byte payloads.
**Concept Header** — `MAGIC="CRS1"`, `VERSION=0x01`, `FLAGS=0x00`, `RSV=0x00`.
| Tag | Field | Type | Card. | Notes |
| ------ | ------------------ | ---- | ----- | ----- |
| `0x40` | `description_cid` | CID | 1 | Canonical COR/1/BCF descriptor for the concept text/essence. |
| `0x41` | `relations_cid` | CID | 1 | Deterministic list CID of outbound relation CIDs. |
**Relation Header** — `MAGIC="CRR1"`, `VERSION=0x01`, `FLAGS=0x00`, `RSV=0x00`.
| Tag | Field | Type | Card. | Notes |
| ------ | ----------------- | ---- | ----- | ----- |
| `0x42` | `source_cid` | CID | 1 | Originating Concept CID. |
| `0x43` | `target_cid` | CID | 1 | Destination Concept or artefact CID. |
| `0x44` | `predicate_cid` | CID | 1 | Registered predicate Concept CID. |
**Validation rules**
* Headers MUST match the values above; mismatches reject as malformed.
* TLVs MUST appear exactly once in the order listed. Missing or out-of-order
TLVs ⇒ `ERR_CRS_TAG_ORDER` (concept) or `ERR_CRR_TAG_ORDER` (relation).
* Duplicate relation tags ⇒ `ERR_CRR_DUPLICATE_TAG`.
* TLV payloads MUST be exactly 32 bytes ⇒ `ERR_CRS_LENGTH_MISMATCH` / `ERR_CRR_LENGTH_MISMATCH`.
* Unknown tags are rejected ⇒ `ERR_CRS_UNKNOWN_TAG` / `ERR_CRR_UNKNOWN_TAG`.
* `predicate_cid` MUST reference a CRS Concept (`ERR_CRR_PREDICATE_NOT_CONCEPT`). When a predicate taxonomy exists, predicates MUST declare `is_a → Predicate` (`ERR_CRR_PREDICATE_CLASS_MISSING`).
**Error mapping (ADR-006)**
| Code | Condition |
| ---- | --------- |
| `ERR_CRS_TAG_ORDER` | Concept TLVs missing, duplicated, or out of order. |
| `ERR_CRS_LENGTH_MISMATCH` | Concept TLV payload not exactly 32 bytes. |
| `ERR_CRS_UNKNOWN_TAG` | Concept TLV tag outside `0x40–0x41`. |
| `ERR_CRR_TAG_ORDER` | Relation TLVs missing, duplicated, or out of order. |
| `ERR_CRR_LENGTH_MISMATCH` | Relation TLV payload not exactly 32 bytes. |
| `ERR_CRR_UNKNOWN_TAG` | Relation TLV tag outside `0x42–0x44`. |
| `ERR_CRR_DUPLICATE_TAG` | Duplicate relation TLV encountered. |
| `ERR_CRR_PREDICATE_NOT_CONCEPT` | `predicate_cid` did not resolve to a CRS Concept. |
| `ERR_CRR_PREDICATE_CLASS_MISSING` | Predicate Concept missing `is_a → Predicate` taxonomy edge. |
**CID derivation**
```
concept_cid = SHA-256("CAS:OBJ\0" || bytes(CRS/1 concept record))
relation_cid = SHA-256("CAS:OBJ\0" || bytes(CRR/1 relation record))
```
Byte-identical records MUST yield identical CIDs; any mutation requires a new
record.
### 7.9 WT/1 Audited Ticket Intake (Normative)
WT/1 (ADR-023) captures auditable intent-to-change tickets as an ADR-003 BCF/1
map. Keys are UTF-8 strings sorted lexicographically; values use canonical BCF
types.
| Key | Type | Cardinality | Notes |
| -------------- | ----------------- | ----------- | ----- |
| `wt.version` | UINT8 | 1 | MUST equal `1`. |
| `wt.author` | CID (hex string) | 1 | CRS Concept or DID capsule representing the submitting actor. |
| `wt.scope` | CID (hex string) | 1 | ADR-010B domain scope concept CID. |
| `wt.intent` | LIST<STRING> | 1 | Non-empty ADR-010 intent identifiers; deduped and byte-lexicographically sorted. |
| `wt.payload` | CID (hex string) | 1 | CRS manifest, change plan, or opaque payload describing proposed work. |
| `wt.timestamp` | UINT64 | 1 | Epoch seconds; MUST be monotonic per `wt.author`. |
| `wt.pubkey` | BYTES[32] | 1 | Ed25519 public key used to verify `wt.signature`; MUST bind to `wt.author`. |
| `wt.signature` | BYTES[64] | 1 | Ed25519 signature over `H("AMDUAT:WT\0" || canonical_bytes_without_signature)`. |
| `wt.parent` | CID (hex string) | 0–1 | Optional lineage pointer to the previous WT/1 ticket for the same author. |
**Encoding rules**
1. `wt.intent` MUST be encoded as a list of unique UTF-8 strings sorted
lexicographically; duplicates ⇒ `ERR_WT_INTENT_DUP`; entries not registered in
ADR-010 ⇒ `ERR_WT_INTENT_UNREGISTERED`.
2. CIDs serialize as lowercase hex strings (32 bytes → 64 hex chars) matching
`SHA-256("CAS:OBJ\0" || payload)` outputs.
3. `wt.signature` is a 64-byte Ed25519 signature; `wt.pubkey` supplies the
32-byte verification key. The signature domain-separates with
`"AMDUAT:WT\0"` and excludes the `wt.signature` field from the canonical byte
stream hashed for verification.
**Validation**
1. Unknown keys ⇒ `ERR_WT_UNKNOWN_KEY`.
2. `wt.version != 1` ⇒ `ERR_WT_VERSION_UNSUPPORTED`.
3. Empty `wt.intent` ⇒ `ERR_WT_INTENT_EMPTY`.
4. `wt.timestamp` less than the prior accepted ticket for the same `wt.author`
⇒ `ERR_WT_TIMESTAMP`. When `wt.parent` is provided, its timestamp MUST NOT
exceed the child timestamp; violations ⇒ `ERR_WT_TIMESTAMP`.
5. Signature verification failure ⇒ `ERR_WT_SIGNATURE`.
6. Routers MUST verify `has_pubkey(wt.author, wt.pubkey)` (or registered
equivalent) ⇒ missing edge raises `ERR_WT_KEY_UNBOUND`.
7. Unknown ADR-010 intent ⇒ `ERR_WT_INTENT_UNREGISTERED`.
8. Router policy rejection of `wt.scope` ⇒ `ERR_WT_SCOPE_UNAUTHORIZED`.
9. Provided `wt.parent` that cannot be resolved ⇒ `ERR_WT_PARENT_UNKNOWN`.
10. Policy required lineage but omitted `wt.parent` ⇒ `ERR_WT_PARENT_REQUIRED`.
**Router integration**
* `POST /wt` (Protected Area) accepts WT/1 payloads, verifies signatures against
`wt.pubkey`, enforces ADR-010 intent membership, validates optional
`wt.parent` lineage, and rejects timestamp regressions.
* `GET /wt/:cid` returns canonical WT/1 bytes for replay.
* `GET /wt?after=<cid>&limit=<n>` paginates deterministically by CID
(byte-lexicographic). `after` is an exclusive bound; routers enforce
`1 ≤ limit ≤ Nmax` and MUST preserve stable replay windows.
* Responses MUST include canonical WT/1 bytes; no rewriting or reformatting is
permitted.
**Evidence & vectors**
* `/amduat/logs/ph04/evidence/wt1/PH04-EV-WT-001/summary.md` — validator run linking
router behaviour to vectors.
* `/amduat/vectors/ph04/wt1/` — fixtures `TV-WT-001…009` covering success,
unknown key, signature failure, timestamp regression, key unbound, intent
unregistered, parent timestamp inversion, scope policy rejection, and
unresolved parent lineage.
### 7.10 CT/1 Header (Normative)
CT/1 headers serialize as ADR-003 BCF/1 maps with fixed key ordering. Keys and
types:
| Key | Type | Notes |
| --------------------- | -------- | ----- |
| `ct.version` | `UINT8` | MUST equal `1`. |
| `ct.rcs_version` | `UINT8` | RCS/1 core schema version; MUST equal `1`. |
| `ct.topology` | `CID` | CRS/1 topology or manifest CID. |
| `ct.ac` | `CID` | AC/1 descriptor CID (ADR-028). |
| `ct.dtf` | `CID` | DTF/1 policy CID (ADR-028). |
| `ct.determinism_level`| `UINT8` | `0` = D1 (bit-exact), `1` = D2 (numeric stable). |
| `ct.kernel_cfg` | `CID` | Opaque kernel/tolerance configuration manifest. |
| `ct.tick` | `UINT64` | Monotonically increasing replay sequence number. |
| `ct.signature` | `BYTES` | 64-byte Ed25519 signature payload. |
**Validation**
1. BCF decode failures ⇒ `ERR_CT_MALFORMED`.
2. Key set/order mismatches ⇒ `ERR_CT_UNKNOWN_KEY`.
3. `ct.version` or `ct.rcs_version` ≠ `1` ⇒ `ERR_CT_VERSION`.
4. `ct.determinism_level ∉ {0,1}` ⇒ `ERR_CT_DET_LEVEL`.
5. Non-canonical CID strings ⇒ `ERR_CT_CID`.
6. `ct.tick` outside `UINT64` range or non-monotone progression ⇒
`ERR_CT_FIELD_TYPE` / `ERR_CT_TICK`.
7. `ct.signature` length mismatch or Ed25519 verification failure ⇒
`ERR_CT_SIGNATURE`.
**Signature rules**
`ct.signature` signs `H("AMDUAT:CT\0" || canonical_bytes_without_signature)`. Public
keys are registered in the determinism catalogue (this section) and referenced by
`ct.kernel_cfg` as needed for tolerance disclosure.
**Evidence & vectors**
* `/amduat/tools/validate/ct1_validator.py` — validation helper covering CT/1,
AC/1, and DTF/1 schemas.
* `/amduat/vectors/ph05/ct1/` — fixtures `TV-CT1-001…004`, `TV-AC1-001…002`,
`TV-DTF1-001…002`.
* `/amduat/tools/ci/ct_replay.py` — replay harness producing
`/amduat/logs/ph05/evidence/ct1/PH05-EV-CT1-REPLAY-001/` (D1 parity + D2
tolerance runs).
### 7.11 SOS/1 Semantic Overlays (Normative)
SOS/1 (ADR-024) attaches typed overlays to CRS Concepts or Relations via an
ADR-003 BCF/1 map signed with the `"AMDUAT:SOS\0"` domain separator.
| Key | Type | Cardinality | Notes |
| -------------- | ------------ | ----------- | ----- |
| `sos.version` | UINT8 | 1 | MUST equal `1`. |
| `sos.subject` | CID (hex) | 1 | CRS Concept or Relation CID receiving the overlay. |
| `sos.predicate`| CID (hex) | 1 | Registered predicate concept describing overlay semantics. |
| `sos.value` | CID (hex) | 1 | Opaque payload (text capsule, BCF/1 manifest, etc.). |
| `sos.policy` | ENUM | 1 | `0=open`, `1=curated`, `2=compat`. |
| `sos.timestamp`| UINT64 | 1 | Epoch seconds when authored. |
| `sos.signature`| BYTES[64] | 1 | Ed25519 signature over `H("AMDUAT:SOS\0" || canonical_bytes_without_signature)`. |
**Validation**
1. Unknown keys ⇒ `ERR_SOS_UNKNOWN_KEY`.
2. `sos.version != 1` ⇒ `ERR_SOS_VERSION_UNSUPPORTED`.
3. `sos.predicate` MUST resolve to a registered CRS predicate ⇒
`ERR_SOS_PREDICATE_UNREGISTERED`.
4. `sos.policy` outside `{0,1,2}` or disallowed for deployment ⇒
`ERR_SOS_POLICY_INCOMPATIBLE`.
5. Epoch-second timestamps that regress relative to policy baseline MAY raise
`ERR_SOS_TIMESTAMP_REGRESSION`.
6. Signature verification failure ⇒ `ERR_SOS_SIGNATURE_INVALID`.
7. Compat overlays (`sos.policy = 2`) MUST reference MPR/1 + IER/1 artefacts in
certification evidence ⇒ missing references raise
`ERR_SOS_COMPAT_EVIDENCE_REQUIRED`.
**Router integration**
* `POST /sos` (Protected Area) validates predicate registry membership, policy
lane, timestamp discipline, and signatures.
* `GET /sos/:cid` returns canonical SOS/1 bytes for replay.
* `GET /sos?subject=<cid>&after=<cid?>&limit=<n>` paginates overlays
deterministically by CID with stable replay windows.
* Compat responses MUST surface referenced MPR/1 hashes and IER/1 fingerprints
for auditors.
**Evidence & vectors**
* `/amduat/logs/ph04/evidence/sos1/PH04-EV-SOS-001/summary.md` — validator run covering
`TV-SOS-001…006`.
* `/amduat/vectors/ph04/sos1/` — canonical overlay fixtures exercising success,
unregistered predicate, policy mismatch, signature failure, timestamp
regression, and compat evidence gaps.
### 7.12 MPR/1 Model Provenance (Normative)
MPR/1 (ADR-025 v1.0.0) captures canonical model fingerprint triples for compat
policy lanes.
| Key | Type | Cardinality | Notes |
| ------------------ | ------------ | ----------- | ----- |
| `mpr.version` | UINT8 | 1 | MUST equal `1`. |
| `mpr.model_hash` | HEX | 1 | Lowercase hex digest (≥64 chars) of model artefact. |
| `mpr.weights_hash` | HEX | 1 | Lowercase hex digest (≥64 chars) of weights bundle. |
| `mpr.tokenizer_hash` | HEX | 1 | Lowercase hex digest (≥64 chars) of tokenizer assets. |
| `mpr.build_info` | CID *(optional)* | 0..1 | Immutable build metadata capsule. |
| `mpr.signature` | BYTES[64] *(optional)* | 0..1 | Ed25519 signature over `"AMDUAT:MPR\0" || canonical_bytes_without_signature`. |
**Validation**
1. Unknown keys ⇒ `ERR_MPR_UNKNOWN_KEY`.
2. `mpr.version != 1` ⇒ `ERR_MPR_VERSION`.
3. Missing hash fields ⇒ `ERR_MPR_MISSING_FIELD`.
4. Hash fields not lowercase hex (≥64) ⇒ `ERR_MPR_HASH_FORMAT`; zero digests ⇒ `ERR_MPR_HASH_ZERO`.
5. `mpr.build_info` malformed ⇒ `ERR_MPR_BUILD_INFO`.
6. Signature verification failure ⇒ `ERR_MPR_SIGNATURE`.
**Evidence & vectors**
* `/amduat/logs/ph04/evidence/mpr1/PH04-EV-MPR-001/pass.jsonl` — validator harness (`python tools/ci/run_mpr_vectors.py`) covering `TV-MPR-001…003` with summary in `summary.md`.
* `/amduat/vectors/ph04/mpr1/` — fixtures exercising valid record, missing weights hash, and signature domain mismatch.
### 7.13 IER/1 Inference Evidence (Normative)
IER/1 (ADR-026 v1.0.0) binds FER/1 receipts to compat policy envelopes and MPR/1 fingerprints.
| Key | Type | Cardinality | Notes |
| ------------------------ | --------------- | ----------- | ----- |
| `ier.version` | UINT8 | 1 | MUST equal `1`. |
| `ier.fer_cid` | CID | 1 | Referenced FER/1 receipt. |
| `ier.executor_fingerprint` | CID | 1 | MUST equal linked MPR/1 CID. |
| `ier.determinism_level` | ENUM | 1 | FER/1 determinism indicator. |
| `ier.rng_seed` | HEX *(conditional)* | 0..1 | Required (hex) when determinism ≠ `D1`. |
| `ier.policy_cid` | CID | 1 | Compat policy capsule authorising run. |
| `ier.log_digest` | HEX | 1 | `H("AMDUAT:IER:LOG\0" || concat(log.sha256))`. |
| `ier.log_manifest` | MAP *(optional)* | 0..1 | Non-empty list of log entries with `sha256`. |
| `ier.attestations` | LIST<BYTES> *(optional)* | 0..1 | Policy attestations (Ed25519 signatures). |
**Validation**
1. Unknown keys ⇒ `ERR_IER_UNKNOWN_KEY`.
2. `ier.version != 1` ⇒ `ERR_IER_VERSION`.
3. Malformed CIDs ⇒ `ERR_IER_POLICY`.
4. `ier.executor_fingerprint` mismatch ⇒ `ERR_IER_FINGERPRINT`.
5. Missing RNG seed when determinism ≠ `D1` ⇒ `ERR_FER_RNG_REQUIRED`.
6. `ier.log_digest` mismatch or malformed manifest ⇒ `ERR_IER_LOG_HASH` / `ERR_IER_LOG_MANIFEST`.
7. Attestation payloads not raw bytes ⇒ `ERR_IER_MALFORMED`.
**Evidence & vectors**
* `/amduat/logs/ph04/evidence/ier1/PH04-EV-IER-001/pass.jsonl` — validator harness (`python tools/ci/run_ier_vectors.py`) covering `TV-IER-001…004` with manifest summary in `summary.md`.
* `/amduat/vectors/ph04/ier1/` — fixtures exercising success, missing RNG seed, fingerprint mismatch, and log digest mismatch.
---
## 8 – Test Vectors & Conformance
### 8.1 COR/1 & ICD/1
* Payload → CID (algo `0x01`).
* COR/1 streams → CID and back (round-trip identity).
* ICD/1 → `instance_id`.
### 8.2 FCS/1 v1-min
* Positive: `{0x30,0x31,0x32}` only, strict order, valid PCB1, acyclic.
* Negative: any pre-v1-min tags (`0x33/0x34/0x35/0x36`) ⇒ reject per §7.2.
* Arity/PCB mismatch ⇒ `ERR_PCB_ARITY_MISMATCH`.
* Cycle ⇒ `ERR_FCS_CYCLE_DETECTED`.
* Negative: legacy tags (`0x33-0x36`) → `ERR_FCS_UNKNOWN_TAG` per §7.2.
### 8.3 FER/1
* Signed receipt with monotonic timestamps; verify signature, executor set ↔ parity alignment, and linkage to FCS/1.
* Negative: timestamp inversion ⇒ `ERR_FER_TIMESTAMP`; bad signature ⇒ `ERR_FER_SIGNATURE`.
* Negative: parity drift (mismatched executor keys or output digests) ⇒ `ERR_IMPL_PARITY`.
* Negative: unknown TLV tag/cardinality ⇒ `ERR_FER_UNKNOWN_TAG`.
### 8.4 FCT/1
* Multiple FER/1 receipts for same function; verify attestation coverage by policy.
* Negative: mismatched receipt function ⇒ `ERR_FCT_RECEIPT_MISMATCH`.
* Negative: missing attestation when policy ≠ Open ⇒ `ERR_FCT_ATTESTATION_REQUIRED`.
### 8.5 FPD/1
* Deterministic reconstruction of `fpd.digest` over `{FCT/1 bytes, FER/1 receipts, governance edge capsule}` on repeated runs.
* Negative: perturbation of member ordering ⇒ `ERR_FPD_DIGEST`.
* Negative: timestamp regression versus FER receipts or parent digest ⇒ `ERR_FPD_TIMESTAMP`.
**CI Requirements**
* Import/export **byte-identity** round-trip for COR/1/FCS/1/FER/1.
* Canonical TLV/BCF ordering across descriptors.
* Multi-platform reproducibility (≥3) including signature verification parity.
* Timing evidence captured per SRS FR-020 (deterministic envelope).
* Federation digest fixture verifies stable FPD/1 CID under `tools/ci/fct_publish_check.py`.
---
## 9. Security Considerations
* Domain separation strings MUST be exact.
* Hash **exact payload bytes**, never decoded structures.
* Canonical rejection prevents ambiguous encodings.
* Certification places policy/intent in signed FCT/1, not in execution recipes.
---
## 10. Change Management
* **Behavioural semantics are in SRS.**
* Changes here require ADR + CCP approval.
* Versioning follows semantic versioning of encodings.
* On approval, update IDX and SRS references accordingly.
---
## 11. ByteStore API & Persistence Discipline
ByteStore is the canonical persistence boundary layered over COR/1 and ICD/1.
Implementations **must** honour the behaviours in this section; deviations are
governed by ADR-030.
### 11.1 API Surface
| API | Signature | Behaviour | Error Surfaces (ADR-006) |
| -------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `put` | `(payload: bytes) → cid_hex` | Persist raw payload under CID derived from `H("CAS:OBJ\0" || payload)`. | `ERR_POLICY_SIZE`, `ERR_IDENTITY_MISMATCH` |
| `put_stream` | `(chunks: Iterable[bytes]) → cid_hex` | Deterministic chunked ingest; concatenated bytes hash to the same CID as `put`. | `ERR_STREAM_ORDER`, `ERR_STREAM_TRUNCATED` |
| `import_cor` | `(envelope: bytes) → cid_hex` | Validate COR/1, enforce policy, persist canonical envelope without re-encoding. | `ERR_POLICY_SIZE`, COR/1 decoder errors |
| `export_cor` | `(cid_hex: str) → envelope` | Return stored COR/1 bytes; must match the original import byte-for-byte. | `ERR_STORE_MISSING`, `ERR_IDENTITY_MISMATCH` |
| `get` | `(cid_hex: str) → bytes` | Return stored bytes (payload or COR envelope) exactly as persisted. | `ERR_STORE_MISSING` |
| `stat` | `(cid_hex: str) → {present: bool, size: int}` | Probe object presence and payload/envelope size without mutating state. | `ERR_STORE_MISSING` (absence reported via `present`) |
| `assert_area_isolation` | `(public_root: Path, secure_root: Path) → None` | Enforce SA/PA separation; raise if roots overlap or share ancestry. | `ERR_AREA_VIOLATION` |
### 11.2 Deterministic Identity
Canonical identity is derived per COR/1/SRS:
```
cid = algo_id || H("CAS:OBJ\0" || payload)
```
`algo_id` defaults to `0x01` (SHA-256). ByteStore **must** reuse the exact
domain separator and hash to remain compatible with CAS and DDS §1.
### 11.3 COR/1 Round-Trip Identity
`import_cor()` decodes the envelope, enforces policy (size ≤ ICD/1
`max_object_size`), and persists the canonical bytes. `export_cor()` returns the
exact stored envelope; re-encoding is forbidden. Derived CID **must** equal the
envelope’s CID (DDS §2.5, SRS FR-BS-004).
### 11.4 Atomic fsync Ladder
All writes follow the deterministic ladder:
1. Write payload/envelope to a unique `.tmp-<suffix>` file in the shard.
2. `fsync(tmp)` to guarantee payload durability.
3. `rename(tmp, final)`.
4. `fsync(shard directory)` and then `fsync(ByteStore root)`.
Crash-window simulation is exposed via `AMDUAT_BYTESTORE_CRASH_STEP` (“before_rename”).
Implementations **must** honour the hook and leave PA consistent on recovery
(DDS §11.8; vectors TV-BS-005, evidence bundle PH05-EV-BS-001).
### 11.5 SA/PA Isolation & Pathing
Public area (PA) payloads live under case-stable two-level fan-out (`/aa/bb/cid…`).
Secure area (SA) metadata is held outside the PA tree. `assert_area_isolation()`
enforces:
* `public_root != secure_root`
* neither root is an ancestor of the other
Violations raise `ERR_AREA_VIOLATION` and **must** be surfaced by callers.
### 11.6 Chunked Ingest Determinism & Policy
`put_stream()` concatenates byte chunks in order, rejecting non-bytes input or
missing data. The resulting CID **must** equal `put(payload)` for the same
payload (SRS FR-BS-005). ByteStore enforces ICD/1 `max_object_size` prior to
persisting data; exceeding the limit raises `ERR_POLICY_SIZE`.
### 11.7 Error Mapping
| Condition | Error Code | Notes |
| ---------------------------------- | --------------------- | -------------------------------------------------------------- |
| Payload exceeds policy limit | `ERR_POLICY_SIZE` | ICD/1 `max_object_size` (ADR-006 policy lane). |
| Streaming chunk type/order invalid | `ERR_STREAM_ORDER` | Non-bytes or out-of-order chunks (deterministic rejection). |
| Streaming missing payload | `ERR_STREAM_TRUNCATED`| Zero-length stream without payload. |
| Stored bytes mismatch CID | `ERR_IDENTITY_MISMATCH` | Raised when existing bytes conflict with derived identity. |
| SA/PA overlap | `ERR_AREA_VIOLATION` | Shared roots or ancestry (secure/public crossing). |
| Crash-window hook triggered | `ERR_CRASH_SIMULATION`| Simulated crash prior to rename/fsync ladder completion. |
| Missing object | `ERR_STORE_MISSING` | Reported when an object path is absent. |
All other errors bubble from COR/1 decoding and map to existing ADR-006 codes
(see §2.7).
### 11.8 Conformance & Evidence
* Vectors: `/amduat/vectors/ph05/bytestore/` (`TV-BS-001…005`).
* Runner: `/amduat/tools/ci/bs_check.py` (dual-run determinism; emits JSONL).
* Evidence: `/amduat/logs/ph05/evidence/bytestore/PH05-EV-BS-001/` (runA/runB +
crash summary).
* Linked ADR: ADR-030 (ByteStore Persistence Contract).
---
## Appendix A — Surface Version Table
| Surface | Version | Notes |
| ------- | ------- | ----- |
| FCS/1 | v1-min | Execution-only descriptor (ADR-016); governance fields live in FCT/1. |
| FER/1 | v1.1 | Parity-first receipts with run_id dedup, executor fingerprints, typed logs, RNG envelope (ADR-017). |
| FCT/1 | v1.0 | Certification transactions binding policy/intent/attestations; publishes FER/1 receipts. |
| FPD/1 | v1.0 | Single-digest publication capsule linking FCT/1 and FER/1 sets. |
---
**End of DDS 0.5.0**
---
## Document History
* 0.2.1 (2025-10-26) — Updated Phase Pack references; byte semantics unchanged; ADR-012 no-normalization.
* 0.2.2 (2025-10-26) — Promoted PH01 design surfaces to Approved; synchronized anchors.
* 0.2.3 (2025-10-27) — Marked DDS scope as PH01-only and referenced FPS/1 surfaces.
* **0.2.4 (2025-11-14):** Added FCS/1 & PCB1 TLVs plus FER/1 receipt and FCT/1 transaction schemas with rejection mapping.
* **0.2.5 (2025-11-15):** Registered PCB1 header invariants and arity/cycle validation errors.
* **0.2.6 (2025-11-19):** Registered `ERR_EXEC_TIMEOUT` for deterministic timing envelope.
* **0.3.0 (2025-11-02):** Trimmed **FCS/1 to v1-min** (execution recipe only: `function_ptr`, `parameter_block`, `arity`). Moved **intent/roles/scope/policy** to **FCT/1**; clarified provenance lives in **FER/1**. Added rejection guidance for legacy FCS tags.
* **0.3.1 (2025-11-20):** Registered `ERR_FCS_UNKNOWN_TAG`; clarified that any legacy governance tag in FCS/1 is a hard rejection. No other layout changes.
* **0.3.2 (2025-11-21):** Adopted parity-first FER/1 TLVs (executor set, parity vector, context/witness hooks), registered `ERR_IMPL_PARITY` and `ERR_FER_UNKNOWN_TAG`, and refreshed conformance guidance.
* **0.3.3 (2025-11-22):** Added FPD/1 publication digest schema, registered federation digest/timestamp errors, and wired CI fixtures to deterministic publish checks.
* **0.3.5 (2025-11-07):** Added surface version table and aligned FER/1 v1.1 maintenance metadata for Phase 04 handoff.
* **0.3.6 (2025-11-08):** Seeded PH04 linkage & semantic placeholder section (DDS §7.8).
* **0.3.7 (2025-11-08):** Seeded FLS/1 placeholder TLV table aligned with ADR-018 v0.3.0.
* **0.3.8 (2025-11-08):** Registered FLS/1 TLV registry (0x60–0x65), error mapping, and conformance vectors aligned with ADR-018 v0.4.0.
* **0.3.9 (2025-11-09):** Locked CRS/1 concept/relation TLVs and registered FLS payload CID/type errors with conformance evidence.
* **0.4.0 (2025-11-08):** Promoted §7.8 FLS/1 & CRS/1 TLVs with error mapping and GS/1 snapshot evidence.
* **0.4.1 (2025-11-09):** Extended CRS predicate rules and mapped new validation errors
* **0.4.2 (2025-11-09):** Registered router error codes (`ERR_FLS_UNKNOWN_TAG`, `ERR_FLS_TAG_ORDER`, `ERR_FLS_SIGNATURE`) and FPD parent-policy errors with GS diff evidence pointer.
* **0.4.3 (2025-11-09):** Added WT/1 intake layout, validation errors, and router API integration (§7.9).
* **0.4.4 (2025-11-20):** Refined WT/1 (§7.9) with `wt.pubkey`, signature preimage exclusion, lineage/policy errors, and
expanded validator vector coverage.
* **0.4.6 (2025-11-22):** WT/1 and SOS/1 conformance evidence sealed via PH04-M4/M5 audit bundles.
* **0.4.5 (2025-11-21):** Registered SOS/1 overlays (§7.10) with compat evidence enforcement, aligned WT/1 error mapping (`ERR_WT_KEY_UNBOUND`, `ERR_WT_INTENT_UNREGISTERED`, `ERR_WT_PARENT_REQUIRED`), and expanded vector coverage to `TV-WT-001…009`.
* **0.4.7 (2025-11-23):** Documented MPR/1 and IER/1 schemas, error surfaces, and validator evidence for compat policy lane.
* **0.4.8 (2025-11-24):** Added §7.10 CT/1 header schema with error codes and renumbered downstream sections for PH05 replay.
* **0.5.0 (2025-11-11):** Added §11 ByteStore API & Persistence discipline covering API surface, fsync ladder, SA/PA isolation, streaming determinism, and ADR-006 error mapping.

223
tier1/fcs.md Normal file
View file

@ -0,0 +1,223 @@
# AMDUAT-FCS/1 — Functional Composition Surface Specification
Status: Draft | Owner: Architecture | Version: 0.2.2 | Last Updated: 2025-11-30 | SoT: Yes
Tags: [composition, execution]
identity_authority: amduat.programme
lineage_id: L-PENDING-FCS1
doc_code: AMDUAT-FCS/1
code_status: tentative
doc_code_aliases: []
location: /amduat/tier1/fcs.md
surface: developer
internal_revision: 3
provenance_mode: full
---
## Scope
**AMDUAT-FCS/1** defines the **deterministic execution recipe** for composite and custom function descriptors.
It links **FPS/1 primitives** to **canonical parameter blocks (PCB1)** and declares **arity**.
**FCS/1 carries no governance, policy, or intent metadata.** Those live in **FCT/1** (certification) and registry sidecars. Provenance for a *run* lives in **FER/1**.
This keeps FCS/1 lean, purely executable, and byte-stable.
---
## Relationship to Other Surfaces
| Surface | Role |
| ----------- | -------------------------------------------------------------------------- |
| **ADR-016** | Canonical semantics of FCS/1 (execution recipe only) |
| **ADR-017** | FER/1 (run evidence) and FCT/1 (certification with intent/policy) |
| **SRS** | FR-014/FR-015 (composition determinism), FR-021 (acyclic), FR-020 (timing) |
| **DDS** | Binary encodings for FCS/1/PCB1 and FER/1/FCT/1 |
**Design separation (normative):**
* **FCS/1** → execution recipe (this file).
* **FER/1** → evidence of one evaluation (timestamps, output, environment, signature).
* **FCT/1** → certification transaction (intent/scope/roles/authority/policy snapshot).
---
## Canonical Descriptor Structure (FCS/1)
FCS/1 descriptors are stored as **COR/1 payloads** with fixed header:
```
MAGIC = "FCS1"
VERSION = 0x01
FLAGS = 0x00
RSV = 0x00
```
### TLV Fields (strict order; v1-min)
| Tag | Name | Type | Card. | Description |
| ---- | ----------------- | ------ | ----: | -------------------------------------------------- |
| 0x30 | `function_ptr` | CID | 1 | CID of FPS/1 primitive or another FCS/1 descriptor |
| 0x31 | `parameter_block` | CID | 1 | CID of canonical parameter array (PCB1 layout) |
| 0x32 | `arity` | VARINT | 1 | Expected parameter slot count (minimal VARINT) |
Rules:
* **Order is strict** (`0x30`, `0x31`, `0x32`), each appears **exactly once**.
* **Unknown/extra tags are invalid**.
* Descriptors are **immutable**; any change yields a **new CID**.
---
## Parameter Blocks (PCB1 layout)
Parameter arrays referenced by `parameter_block` are COR/1 payloads with header `"PCB1"`.
| Tag | Field | Type | Description |
| ---- | --------------- | ----- | ----------------------------------------------------- |
| 0x50 | `slot_manifest` | BCF/1 | Canonical slot descriptors `{index,name,type,digest}` |
| 0x51 | `slot_data` | BYTES | Packed binary slot values matching manifest order |
Slot types (informative excerpt):
* `UINT64` (LE 8 bytes), `CID` (32-byte hash), `BYTES` (VARINT length + bytes).
Slots appear in ascending `index`. Missing numeric slots default to `0`.
Validation errors (symbolic per ADR-006): `ERR_PCB_MANIFEST_ORDER`, `ERR_PCB_DIGEST_MISMATCH`, `ERR_PCB_ARITY_MISMATCH`.
---
## Validation (normative)
Implementations **MUST** validate:
1. **TLV order & uniqueness** for FCS/1 (`0x30`,`0x31`,`0x32`).
* Violations ⇒ `ERR_FCS_TAG_ORDER`, `ERR_FCS_DUPLICATE_TAG`, or `ERR_FCS_UNKNOWN_TAG`.
2. **PCB1 dereference & format** for `parameter_block`.
* Non-PCB1 or malformed ⇒ `ERR_FCS_PARAMETER_FORMAT`.
* Manifest ordering/digest/arity mismatches ⇒ PCB1 errors above.
3. **Arity match**: `arity` equals PCB1 slot count.
* Mismatch ⇒ `ERR_PCB_ARITY_MISMATCH`.
4. **Acyclicity**: Descriptor graph is acyclic.
* Self-reference/cycle detected ⇒ `ERR_FCS_CYCLE_DETECTED`.
**Determinism:** Identical descriptors (bytes) must resolve to identical CIDs and yield identical execution results under the same inputs/environment (SRS FR-014/015).
---
## Out-of-Scope (for FCS/1)
* **Intent, policy, authority, roles, domain scope** — encoded in **FCT/1** (certification).
* **Provenance of a run** — encoded in **FER/1** (evaluation receipts).
* **Human notes/annotations** — registry sidecars (non-canonical).
* **Timing envelope** — verified at harness level (SRS FR-020), logged as evidence.
---
## PH12 Import Descriptors (Registered)
The following FCS/1 v1-min descriptors are registered for PH12 import harnesses. They are execution-only recipes whose semantics are governed by MS/1 concepts and PH12 import specs; provenance lives in FER/1 receipts.
### `ms.docs.ingest_repo_doc.v1` (doc-ingest recipe)
- **Descriptor CID (FCS/1):** `0x0001:872ba0e9536d52153147dc4eab3fd6cc3cd0cbbb0211df810dbb33c1c8d35916`
- **Function pointer (`function_ptr`):**
- ASL/1 Reference over JSON payload `{"concept_id":"ms.docs.ingest_repo_doc.v1"}`.
- `function_ptr_ref = 0x0001:212fa9358c7b2aaa1d1e5a25906e4deb814fd5c71ac06dbbd2ed7b58d08864ef`.
- **Parameter block (`parameter_block`):**
- PCB1 payload with 3 slots matching FER/1 `subject.input_refs`:
- `blob_ref` (index 0, type `cid`) → `doc.asl_blob_ref`
- `snapshot_ref` (index 1, type `cid`) → `doc.asl_snapshot_ref`
- `store_ref` (index 2, type `cid`) → `doc.asl_store_ref`
- `parameter_block_ref = 0x0001:1ffe8a4454e4a197a9528290aa8ba2025bc9faf4fb1b22b6c5bfbb43e78caa48`.
- **Arity:** `3` (matches slot count and PCB1 manifest).
### `docgraph.encode_edges_from_ingest.v1` (doc-graph encoder recipe)
- **Descriptor CID (FCS/1):** `0x0001:b70330c70754895e9992c7e06aff6687d62e303481056b7e231ecaed634a84b4`
- **Function pointer (`function_ptr`):**
- ASL/1 Reference over JSON payload `{"concept_id":"docgraph.encode_edges_from_ingest.v1"}`.
- `function_ptr_ref = 0x0001:a255b99a214f03b65af041bf6f57704ad90d8c0ca2b9a07df1d23c80f2dc0b9d`.
- **Parameter block (`parameter_block`):**
- PCB1 payload with 3 slots matching FER/1 `subject.input_refs`:
- `doc_version_index_ref` (index 0, type `cid`) → doc-version index Artifact.
- `edge_catalog_ref` (index 1, type `cid`) → edge-type catalog Artifact.
- `encoder_config_ref` (index 2, type `cid`) → encoder-config Artifact.
- `parameter_block_ref = 0x0001:6994b0236929d83c06bf87799cec92bfb744f97f50a8b14d032a3aee8b198242`.
- **Arity:** `3` (matches slot count and PCB1 manifest).
These references are used in PH12 FER/1 receipts via `subject.program_ref` for doc-ingest and doc-graph encoder runs.
---
## Program Reference Convention (informative)
When FER/1 receipts expose a `program_ref` field that points at an FCS/1 recipe, profiles SHOULD use the following convention:
- `program_ref = "fcs:cid:<descriptor_ref>"`, where `<descriptor_ref>` is the ASL/1 Reference of a concrete FCS/1 descriptor.
- Concept identifiers (e.g. `ms.docs.ingest_repo_doc.v1`) MAY be recorded in context bindings, but the canonical program handle used for execution and provenance is the descriptor CID.
PH12 import harnesses follow this convention; see the PH12 Import Descriptors section above for concrete examples.
**PH12 MS/1 import harnesses (registry note):**
- Doc-ingest harness uses the FCS descriptor `fcs:cid:0x0001:872ba0e9536d52153147dc4eab3fd6cc3cd0cbbb0211df810dbb33c1c8d35916` (concept `ms.docs.ingest_repo_doc.v1`).
- Encoder harness uses the FCS descriptor `fcs:cid:0x0001:b70330c70754895e9992c7e06aff6687d62e303481056b7e231ecaed634a84b4` (concept `docgraph.encode_edges_from_ingest.v1`).
- Both run today via the PH08 MS/1 oracle; the pinned descriptors make them FCS-grade programs ready for future PEL/TGK executors.
---
## Governance & Registry Hooks (informative)
* Registries index **FCS/1 CIDs** as recipes.
* Publication and listing **must read policy/intent from FCT/1**, not FCS/1.
* Latest run evidence is discoverable via **FER/1** attached to published artefacts.
* Phase Packs capture evidence and diffs; DOCSTD governs glossary/tags.
## Dependencies (pinned drafts)
FCS/1 relies on upstream drafts; consumers MUST treat these versions as pinned
for this spec and handle later changes as upstream drift:
* FPS/1 v0.4.3 (Draft)
* FER/1 v1.x (current) for run evidence
* FCT/1 (Draft) for certification/intent (referenced, not defined here)
## Evidence
Runtime proof lives in PH06–PH08 harnesses; no direct evidence is bundled in
this spec. Refer to PH06 evidence handles (`PH06-EV-PEL-EXEC-001`, etc.) for
execution harness parity; PH08 reference runs validate MS/1 and downstream
surfaces that consume FCS/1.
---
## Conformance
A conforming implementation MUST:
* Produce/consume FCS/1 with only the **v1-min TLVs** (`0x30`,`0x31`,`0x32`).
* Enforce PCB1 and acyclicity validation.
* Reject unknown/extra/out-of-order tags.
* Keep FCS/1 **free from policy/intent** and other governance data.
Recommended tests:
* Positive: minimal descriptor round-trip, nested FCS/1 composition, PCB1 digest alignment.
* Negative: old/removed tags present ⇒ rejection; cycle detection; arity mismatch.
---
## Document History
* **0.1.0 (2025-11-02)** — Initial draft aligning FCS/1 descriptor semantics, FER/1/FCT/1 integration, and governance hooks.
* **0.1.1 (2025-11-05)** — Added arity validation and cycle detection rules.
* **0.2.0 (2025-11-14)** — **Trimmed to v1-min** (function_ptr, parameter_block, arity). Moved policy/intent/provenance/notes out of FCS/1 to **FCT/1** (intent/policy) and **FER/1** (run evidence); notes to registry sidecars. Kept validation and determinism unchanged.
* **0.2.1 (2025-11-20):** Locked normative text to v1-min TLVs and deferred legacy tag references to history/tests.
* **0.2.2 (2025-11-30):** Added DOCID header, pinned upstream draft dependencies, and clarified evidence references.
---

58
tier1/fls.md Normal file
View file

@ -0,0 +1,58 @@
# AMDUAT-FLS/1 — Functional Linkage Surface Specification
Status: Draft | Owner: Architecture | Version: 0.1.1 | Last Updated: 2025-11-30 | SoT: Yes
Tags: [communication, linkage, deterministic]
identity_authority: amduat.programme
lineage_id: L-PENDING-FLS1
doc_code: AMDUAT-FLS/1
code_status: tentative
doc_code_aliases: []
location: /amduat/tier1/fls.md
surface: developer
internal_revision: 2
provenance_mode: full
## Scope
FLS/1 defines the deterministic interface between certified composites, enabling
canonical message exchange and ledger-based completion tracking.
## Elements
* Session Envelope — capability handshake and deterministic scheduler params
* Channel Catalogue — logical channel definitions (request/response/event)
* Message Envelope — COR/1 payload with (channel-id, ordinal, payload-cid, trace-cid)
* Termination Ledger — final ledger of ordinals and status (complete, abandoned, diverged)
## Next Steps
* Specify binary layout in DDS §9 (placeholder)
* Add behavioural requirements in SRS §3.5 for message ordering and error codes.
* Integrate into PH04 traceability register once phase starts.
## Dependencies (pinned drafts)
FLS/1 relies on upstream drafts; consumers MUST treat these versions as pinned
for this spec and handle later changes as upstream drift:
* DDS v0.x (binary layouts for envelopes/ledgers)
* FER/1 v1.x for run evidence (current)
* FCT/1 (Draft) for certification/intent (referenced, not defined here)
* FPS/1 v0.4.3 (Draft) for primitive byte operations
## Evidence (PH04)
PH04 evidence bundles capture the linkage surface scaffolding:
* `logs/ph04/evidence/fls1/`
* `logs/ph04/evidence/fls1-crs/`
* `logs/ph04/evidence/fls1-router/`
Treat these as sealed references; new work requires explicit reactivation.
## Document History
* **0.1.0 (2025-11-01):** Initial draft defining FLS/1 scope, elements, and next steps.
* **0.1.1 (2025-11-30):** Added DOCID header, pinned draft dependencies, and referenced PH04 evidence bundles.

121
tier1/fps.md Normal file
View file

@ -0,0 +1,121 @@
# 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.

518
tier1/srs.md Normal file
View file

@ -0,0 +1,518 @@
# AMDUAT-SRS — Detailed Requirements Specification
Status: Approved | Owner: Niklas Rydberg | Version: 0.4.0 | Last Updated: 2025-11-11 | SoT: Yes
Tags: [requirements, cas, kheper]
> **Purpose:** Capture normative behavioural requirements for Phase PH01 (Kheper) and beyond. Long-lived semantics live here (not in Phase Packs).
---
## 1. Objectives (from Tier-0 Charter; elaborated)
* Deterministic addressing: identical payload bytes **MUST** yield identical CIDs.
* Immutability: new bytes → new CID; objects MUST NOT be mutated in place.
* Integrity by design: `verify()` MUST detect corruption; zero false positives.
* Instance isolation: storage layout and runtime state are implementation detail.
* Binary canonical substrate: COR/1 is the normative import/export envelope.
* Instance identity: ICD/1 defines stable `instance_id` for future transaction bindings.
* Crypto agility: default SHA-256; algorithm IDs extensible.
* Minimal tooling: reference CLI (`amduatcas`) and C library.
* Conformance: golden vectors and cross-impl CI enforce byte-identity.
---
## 2. Scope (Behavioural)
### 2.1 In Scope
* Local, single-node Content-Addressable Storage (CAS)
* Deterministic hashing with domain separation
* Canonical envelopes (COR/1) and instance descriptor (ICD/1)
* CRUD-adjacent operations: put/get/stat/exists/verify
* Import/export of canonical bytestreams
* Optional listing/gc semantics
### 2.2 Out of Scope (for PH01)
* Networking, replication, consensus
* Multi-object transactions
* Semantic/provenance graphing
* Encryption/ACLs (layer externally)
---
## 3. Functional Requirements
### FR-001 Deterministic CID Production
Given identical payload bytes and algo_id, the CID **MUST** match across compliant implementations.
### FR-002 Immutability
Objects **MUST NOT** be mutated; new payload → new CID.
### FR-003 Idempotent Put
Concurrent `put()` of identical payload MUST yield one canonical object; object integrity preserved.
### FR-004 Verification
`verify(CID)` MUST recompute the CID and detect corruption; zero false positives.
### FR-005 Import/Export Canonicality
Importing COR/1 and then exporting it MUST yield byte-identical bytestreams.
### FR-006 Size Validation
`get()` MUST validate payload length according to COR/1.
### FR-007 Optional Verify-on-Read Policy
Policy MAY require verify for cold reads; MUST NOT corrupt payload if disabled.
### FR-008 Canonical Rejection
CAS decoders MUST reject:
* out-of-order TLV tags
* duplicate TLV tags
* extraneous tags
* trailing bytes
* malformed or over-long VARINT encodings
* payload length mismatches
Rejection MUST be deterministic and symbolic.
### FR-009 Concurrency Discipline
Concurrent `put()` operations for identical payloads MUST NOT yield divergent COR/1 envelopes. Only one canonical envelope may result.
### FR-010 Raw Byte Semantics
CAS MUST operate strictly over exact payload bytes. No normalization (newline, whitespace, UTF-8 interpretation, or Unicode equivalence) SHALL occur.
### FR-011 Filesystem Independence
Consensus behaviour MUST NOT depend on:
* directory entry ordering
* timestamp metadata
* filesystem case sensitivity
* locale or regional configuration
### FR-012 Deterministic Failure
Malformed objects MUST be rejected. CAS MUST NOT auto-repair or normalize COR/1 envelopes.
### FR-013 Resource Boundaries
Resource exhaustion (disk full, allocation failure) MUST fail atomically and leave no partial objects visible.
### FR-014 FCS/1 Descriptor Determinism (v1-min)
Composite and custom functions MUST be expressed as canonical **FCS/1** descriptors that contain **only the execution recipe**:
`function_ptr`, `parameter_block (PCB1)`, and `arity`.
Identical descriptors SHALL hash to identical CIDs and MUST remain immutable after publication. **No policy/intent/notes** appear in FCS/1.
### FR-015 Registry Determinism (Descriptor Admission)
Functional registries MUST admit **only canonical FCS/1 descriptors** (per FR-014) and enforce descriptor validation (TLV order, PCB1 arity, acyclicity).
Registries MUST NOT infer or embed policy/intent into descriptors; publication governance is handled at certification time (FR-017).
### FR-016 Evaluation Receipt Integrity (FER/1)
Every execution of a composite function under curated or locked policies MUST emit a **FER/1** receipt. The receipt SHALL encode, in canonical TLV order, at least the following evidence:
1. `function_cid` → evaluated FCS/1 descriptor (v1-min) preserving CIP indirection.
2. `input_manifest` → GS/1 BCF/1 set of consumed input CIDs (deduped and byte-lexicographic).
3. `environment` → ICD/1 (or PH03 env capsule) snapshot pinning toolchain/runtime state.
4. `evaluator_id` → stable evaluator identity bytes.
5. `executor_set` → implementations that executed the recipe, keyed in canonical byte order.
6. `parity_vector` → per-executor digests with matching `executor` ordering, shared `output` (`== output_cid`), and `sbom_cid` entries.
7. `executor_fingerprint` + `run_id` → optional SBOM fingerprint CID and deterministic dedup hash (`H("AMDUAT:RUN\0" || function || manifest || env || fingerprint)`).
8. `logs` → typed evidence capsules binding `kind`, `cid`, and `sha256` for stdout/stderr/metrics traces.
9. `limits` → declared execution envelope (`cpu_ms`, `wall_ms`, `max_rss_kib`, `io_reads`, `io_writes`).
10. `determinism_level` / `rng_seed` → declared determinism class (`D1_bit_exact` default, `D2_numeric_stable` requires a 0–32 byte seed).
11. `output_cid` → single canonical output CID for the run.
12. `started_at` / `completed_at` → epoch-second timestamps satisfying FR-020 bounds.
13. `signature` → Ed25519 metadata verifying `H("AMDUAT:FER\0" || canonical bytes)`.
Receipts MAY include optional `logs` (typed capsules), `context`, `witnesses`, `parent`, and `signature_ext` TLVs but MUST NOT leak policy/intent (those belong to FCT/1).
From Phase 04 onwards, governance and runtime layers MUST require FER/1 v1.1 receipts; ER/1 artefacts remain valid only as historical evidence and SHALL NOT satisfy FR-016 compliance gates.
Parity discipline is mandatory: unsorted executor keys or mismatched parity orderings SHALL raise `ERR_IMPL_PARITY_ORDER`; divergent outputs or missing executors SHALL raise `ERR_IMPL_PARITY`. Unknown TLVs or cardinality violations SHALL raise `ERR_FER_UNKNOWN_TAG`. GS/1 manifest violations emit `ERR_FER_INPUT_MANIFEST_SHAPE`; missing RNG seed when determinism ≠ D1 emits `ERR_FER_RNG_REQUIRED`. All signatures MUST verify against the domain-separated hash (`ERR_FER_SIGNATURE` on failure).
### FR-017 Certification Transactions (FCT/1: Policy & Intent)
Certification events MUST be recorded as **FCT/1** transactions that aggregate one or more FER/1 receipts and bind **registry policy, intent, domain scope, and authority role**.
Transactions MUST include attestations whenever `registry_policy != 0` and SHALL expose publication pointers when federated.
**All intent/scope/role/authority metadata lives in FCT/1 (not in FCS/1).**
### FR-BS-001 ByteStore Deterministic Identity
ByteStore SHALL derive CIDs using the canonical CAS domain separator: `CID = algo || H("CAS:OBJ\0" || payload)`.
The derived CID returned by `put()` and `import_cor()` MUST match the CID embedded in COR/1 envelopes and SHALL remain stable across runs, implementations, and ingest modes (DDS §11.2; ADR-030).
### FR-BS-002 Atomic Durability Ladder
ByteStore persistence MUST follow the atomic write ladder: write → `fsync(tmp)` → `rename` → `fsync(shard)` → `fsync(root)`.
Crash-window simulations triggered via `AMDUAT_BYTESTORE_CRASH_STEP` MUST leave the public area consistent upon recovery, with no visible partial objects (DDS §11.4; ADR-030; evidence PH05-EV-BS-001).
### FR-BS-003 Secure/Public Area Isolation
ByteStore SHALL enforce SA/PA isolation such that public payload roots and secure state roots are disjoint and non-overlapping.
Violations MUST raise `ERR_AREA_VIOLATION` and SHALL be surfaced to callers (DDS §11.5; ADR-030).
### FR-BS-004 COR/1 Round-Trip Identity
Importing COR/1 bytes via ByteStore and exporting the same CID MUST yield a byte-identical envelope.
Any mismatch between stored bytes and derived CID SHALL raise `ERR_IDENTITY_MISMATCH` (DDS §11.3; ADR-030).
### FR-BS-005 Streaming Determinism & Policy Enforcement
Chunked ingestion (`put_stream`) MUST produce the same CID as single-shot `put` for equivalent payloads and reject non-bytes or missing data with deterministic errors (`ERR_STREAM_ORDER`, `ERR_STREAM_TRUNCATED`).
ByteStore SHALL enforce ICD/1 `max_object_size` for all ingest paths, raising `ERR_POLICY_SIZE` when exceeded (DDS §11.6–11.7; ADR-030).
### FR-022 Federation Publication Digest (FPD/1)
Every publish event emerging from an FCT/1 certification MUST emit exactly one **FPD/1** digest satisfying ADR-007 single-digest guarantees.
The digest SHALL canonically hash the certified FCT/1 record, all attested FER/1 receipts, and the emitted governance edges (`certifies`, `attests`, `publishes`).
Implementations MUST persist the FPD/1 bytes alongside the FCT/1 payload under `/logs/ph03/evidence/fct/` (or successor evidence path) and reference the resulting CID from `fct.publication`.
Repeated invocations over identical inputs SHALL reproduce the same digest; mismatches SHALL be treated as certification failures.
### FR-018 Provenance Enforcement
Caching or replay layers MUST validate FER/1 receipts and FCT/1 transactions before serving composite outputs. Serving uncertified artefacts when policy requires certification is forbidden.
### FR-019 Transaction Envelope Rejection
Systems MUST reject FER/1 or FCT/1 envelopes whose CID lineage does not match the referenced FCS/1 descriptor, whose timestamps are non-monotonic, or whose signatures/attestations fail verification.
### FR-020 Deterministic Execution Envelope
| ID | Statement | Verification | Notes |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **FR-020 — Deterministic Execution Envelope** | Each executor SHALL complete within a bounded deterministic time envelope (default 5 s). Execution time SHALL be measured and logged as evidence. Non-termination SHALL yield symbolic error `ERR_EXEC_TIMEOUT`. | Verified via CI parity harness and evidence file `/logs/ph03/evidence/<date>-execution-times.jsonl`. | Implements Maat’s Balance principle. Tags: [deterministic-timing, evidence, maat-balance]. |
### FR-021 Acyclic Composition
FCS/1 descriptors referencing FPS/1 primitives, PCB1 parameter blocks, or nested FCS/1 descriptors MUST form an acyclic graph.
Registries SHALL reject submissions introducing self-references or cycles and emit `ERR_FCS_CYCLE_DETECTED` or
`ERR_PCB_ARITY_MISMATCH` when arity metadata conflicts with PCB1 manifests.
### FR-028 Concept-Native Domain Materialization
Federated domain manifests SHALL be materialized exclusively from CRS Concepts
and Relations. Given a DomainNode Concept, registries MUST traverse
`hasManifest` → `ManifestEntry` Concepts, extract `entryName` and
`entryChildVersion` relations, dedupe the `(name, version)` set, and compute the
GS/1 domain state deterministically. Duplicated pairs trigger `ERR_DG_DUP_ENTRY`;
missing relations trigger `ERR_DG_ENTRY_INCOMPLETE`; self references or
ancestor loops raise `ERR_DG_CYCLE`. Evidence: `tools/ci/dg_snapshot.py`
→ `logs/ph04/evidence/dg1/PH04-EV-DG-001/`.
Operational linkage: router listings (`GET /links`) MUST return entries sorted
lexicographically by `fls_cid` and treat `since` query parameters as exclusive
lower bounds, ensuring deterministic replay of linkage events.
### FR-029 Publication Recursion Discipline
Publication Concepts SHALL declare their supporting FPD/1 digest, GS/1 cover
state, endorsed member FPD CIDs, and optional lineage parent using CRS
relations (`covers`, `endorses`, `parent`). Validators MUST recompute GS/1 from
the FPD payload, enforce duplicate-free membership, and detect recursive
cycles (`ERR_FPD_CYCLE`). Timestamp regressions raise `ERR_FPD_TIMESTAMP`; state
mismatches raise `ERR_PUB_STATE_MISMATCH`. Evidence: `tools/ci/pub_validate.py`
→ `logs/ph04/evidence/pub1/PH04-EV-PUB-001/`.
Operational linkage: non-genesis publications SHOULD enable the parent-required
policy, supplying `fpd.parent` and guaranteeing strictly monotonic
`fpd.timestamp` to align with ADR-019 v1.2.1 and PH04 parent-policy harnesses.
### FR-030 Predicate Concepts
Every CRR/1 relation predicate MUST resolve to a CRS Concept. When the
taxonomy defines a `Predicate` Concept, predicate entries SHALL expose an
`is_a` edge into that class. Missing predicate Concepts raise
`ERR_CRR_PREDICATE_NOT_CONCEPT`; missing taxonomy membership raises
`ERR_CRR_PREDICATE_CLASS_MISSING`. Evidence: CRS validator vectors and
`logs/ph04/evidence/crs1/PH04-EV-CRS-001.md`.
Operational linkage: FPD feed endpoints SHALL implement stateless, content-anchored pagination over parent-chained publications. `GET /feed/fpd` MUST traverse the publisher’s current tip toward genesis until either the caller-provided `limit` is satisfied or the supplied `since` CID is encountered; identical `publisher_id`, `since`, and `limit` inputs SHALL yield identical CID sequences. Detail lookups (`GET /feed/fpd/:cid`) SHALL expose publisher, members, parent, and state metadata without server-side session state. Evidence: `tools/ci/feeds_check.py` → `/amduat/logs/ph04/evidence/feeds/PH04-EV-FEEDS-001/pass.jsonl`.
### FR-031 Authority Anchoring via CRS & FPD
Publishing authorities SHALL represent identities as CRS Concepts linked via
`owns` and `hasRole` relations to key material and governance roles. Signatures
remain confined to FCT/1 and FPD/1 surfaces; CRS layers stay unsigned. FLS/1
transport MAY carry Concept or Relation payloads but MUST NOT mutate them and
MUST perform payload-kind checks when requested (`--check-crs-payload`).
Operational linkage: FLS router deployments SHALL expose `POST /fls`,
`GET /fls/:cid`, `GET /links`, `GET /healthz`, and `GET /readyz` endpoints and
enforce SA/PA separation (`ERR_AREA_VIOLATION` if misconfigured) so that public
ingest never mutates state areas directly. Audited ticket intake SHALL be
implemented via WT/1 (ADR-023) with:
* `POST /wt` (Protected Area) accepting WT/1 BCF/1 payloads, validating
`has_pubkey(wt.author, wt.pubkey)` (or registered equivalent), verifying
signatures over `H("AMDUAT:WT\0" || canonical_bytes_without_signature)`,
enforcing registered ADR-010 intents (deduped + byte-lexicographically
sorted), ensuring monotonic `wt.timestamp` per `wt.author`, and optionally
chaining `wt.parent` lineage. Violations yield `ERR_WT_SIGNATURE`,
`ERR_WT_KEY_UNBOUND`, `ERR_WT_INTENT_UNREGISTERED`, `ERR_WT_INTENT_DUP`,
`ERR_WT_INTENT_EMPTY`, `ERR_WT_TIMESTAMP`, `ERR_WT_PARENT_UNKNOWN`, or
`ERR_WT_PARENT_REQUIRED`. Router policy MUST surface scope denials as
`ERR_WT_SCOPE_UNAUTHORIZED` and log the governing policy capsule.
* `GET /wt/:cid` returning the canonical WT/1 bytes for any accepted ticket.
* Deterministic pagination (`GET /wt?after=<cid>&limit=<n>`) that emits WT/1
entries in byte-lexicographic CID order with stable page boundaries. The
`after` parameter is an exclusive bound and routers SHALL enforce
`1 ≤ limit ≤ Nmax` to guarantee replay stability.
Evidence: `/amduat/logs/ph04/evidence/wt1/PH04-EV-WT-001/summary.md` captures the
validator run over vectors `TV-WT-001…009`, ensuring unknown keys, signature
failures, timestamp regressions (including parent inversions), unbound keys,
unregistered intents, policy rejections, and unresolved parents reject as
specified.
Compat overlays SHALL reference ADR-025 MPR/1 provenance capsules and ADR-026
IER/1 inference evidence when operating in policy lane `compat`. Routers MUST
validate that `executor_fingerprint` equals the supplied MPR/1 CID, enforce
`determinism_level` plus `rng_seed` (raising `ERR_FER_RNG_REQUIRED` when
omitted), and verify log digests via the IER/1 manifest before accepting
overlays (`ERR_IER_LOG_HASH`/`ERR_IER_LOG_MANIFEST`). Evidence surfaces
`/amduat/logs/ph04/evidence/mpr1/PH04-EV-MPR-001/pass.jsonl` and
`/amduat/logs/ph04/evidence/ier1/PH04-EV-IER-001/pass.jsonl` prove vector
coverage `TV-MPR-001…003` (hash triple, missing weights, signature domain) and
`TV-IER-001…004` (ok, missing seed, fingerprint mismatch, log digest mismatch)
respectively with scenario summaries in accompanying `summary.md` files.
### FR-032 CT/1 Deterministic Replay (D1)
Given identical AC/1 + DTF/1 + topology inputs, executing the runtime twice in
isolation MUST produce byte-identical CT/1 snapshots (header and payload) with
matching CIDs whenever `ct.determinism_level = 0`. Evidence:
`tools/ci/ct_replay.py` (`runA`/`runB`) →
`/amduat/logs/ph05/evidence/ct1/PH05-EV-CT1-REPLAY-001/`.
### FR-033 CT/1 Numeric Stability (D2)
When `ct.determinism_level = 1`, numeric observables MAY diverge, but the
maximum absolute delta MUST remain within the tolerance documented by
`ct.kernel_cfg`. Evidence: `tools/ci/ct_replay.py` D2 replay outputs and kernel
configuration manifests in the same evidence set.
### FR-034 CT/1 Header Integrity
CT/1 headers MUST follow ADR-027: canonical BCF/1 key ordering, rejection of
unknown keys, monotonic `ct.tick`, canonical `cid:` formatting for topology and
AC/1/DTF/1 pointers (ADR-028), and Ed25519 signatures over
`H("AMDUAT:CT\0" || canonical_bytes_without_signature)`. Evidence:
`tools/validate/ct1_validator.py` with vectors
`/amduat/vectors/ph05/ct1/TV-CT1-001…004` and AC/DTF fixtures
`TV-AC1-001…002`, `TV-DTF1-001…002`.
---
## 4. Non-Functional Requirements
### NFR-001 Determinism
Platform/language differences MUST NOT affect CID.
### NFR-002 Performance
Put/get latency MUST remain within configured OPS budgets.
### NFR-003 Reliability
CAS operations MUST be atomic; partial writes MUST NOT be visible.
### NFR-004 Portability
Implementations MUST operate on common filesystems.
### NFR-005 Security Posture
Domain separation strings MUST be applied for all hashed surfaces.
### 4.3 Future Scope Alignment (Informative)
Phase 02 introduces deterministic transformation primitives (**FPS/1**) extending the Kheper CAS model defined herein.
See `/amduat/arc/adrs/adr-015.md` and `/amduat/tier1/fps.md` for details.
No behavioural changes apply retroactively to PH01 surfaces.
---
## 5. Data Model (Behavioural View)
* CAS objects identified strictly by CID.
* COR/1 envelope provides size, payload, algo_id.
* ICD/1 descriptor provides instance configuration.
> See DDS §2 (COR/1) and §3 (ICD/1) for normative byte layouts.
---
## 6. API Semantics
### `put(payload_bytes, algo_id=default) → CID`
* Compute CID using domain separation: `CID = algo_id || H("CAS:OBJ\0" || payload_bytes)`
* If CID exists: return existing CID (idempotent)
* If absent: write canonical COR/1 envelope atomically
* Reject on size limit breach, malformed payload, non-canonical COR/1, I/O errors
* Writes MUST be atomic: temp file → fsync → rename → fsync parent dir
### `get(CID) → payload_bytes`
* Retrieve raw payload bytes
* MUST validate canonical COR/1 envelope
* Implementation MAY verify hash on read by policy
* Reject on missing object, hash mismatch
### `exists(CID) → bool`
* Return true if object is present and canonical
### `stat(CID) → { present, size, algo_id }`
* MUST return canonical metadata
### `verify(CID) → { ok|error, expected:CID, actual:CID }`
* Recompute CID from canonical bytes
* MUST detect corruption and reject non-canonical encodings
### `import(stream_COR1) → CID`
* Validate canonical TLV ordering
* Reject duplicate tags, extraneous tags, malformed VARINTs
* MUST round-trip to identical CID
### `export(CID) → stream_COR1`
* Emit canonical envelope; re-encoding MUST preserve canonical bytes
### Deterministic Errors
Errors MUST be emitted as stable symbolic codes including but not limited to:
* `E_CID_NOT_FOUND`
* `E_CORRUPT_OBJECT`
* `E_CANONICALITY_VIOLATION`
* `E_IO_FAILURE`
---
## 7. Success Criteria
* Byte-for-byte CID agreement (≥ 3 platforms)
* Zero false positives in `verify()`
* Idempotent concurrent `put()`
* COR/1 import/export round-trips cleanly
---
## 8. GC Semantics (Behavioural)
* Reachability from configured roots
* Dry-run mode MUST NOT delete
* Removal MUST be atomic per object
---
## 9. Acceptance Criteria (Phase Exit)
* Golden vectors published
* Cross-impl CI passing
* COR/1 and ICD/1 documented in DDS
* Security posture validated by SEC
---
## 10. Traceability
* Requirements link to tests/defects in Phase Packs
* ADRs reference affected FR/NFR IDs
---
## 11. Future Phases
* Multi-object transactions bind to `instance_id`
* Provenance graph consumes COR/1 metadata
---
## 12. Functional Primitive Surface (FPS/1)
> Defines the canonical deterministic operations over canonical payloads.
> Each primitive produces exactly one payload and one CID.
| Primitive | Signature | Description | Determinism / Errors |
| ------------- | ------------------------------ | ------------------------------------------- | ---------------------------------------------- |
| `put` | `(payload_bytes) → CID` | Canonical write, atomic fsync ladder. | ADR-006 `ERR_IO_FAILURE`, `ERR_NORMALIZATION`. |
| `get` | `(CID) → payload_bytes` | Fetch canonical bytes. | `ERR_CID_NOT_FOUND`. |
| `slice` | `(CID, offset, length) → CID` | Extract contiguous bytes. | `ERR_SLICE_RANGE`. |
| `concatenate` | `([CID₁,…,CIDₙ]) → CID` | Sequential join of payloads. | `ERR_EMPTY_INPUTS`. |
| `reverse` | `(CID, level) → CID` | Reverse payload order (bit/byte/word/long). | `ERR_REV_ALIGNMENT`, `ERR_INVALID_LEVEL`. |
| `splice` | `(CID_a, offset, CID_b) → CID` | Insert payload b into a at offset. | `ERR_SPLICE_RANGE`. |
**Determinism:** identical inputs → identical outputs.
**Immutability:** inputs never mutated.
**Closure:** outputs valid for reuse as inputs to any primitive.
**Error handling:** all symbolic per ADR-006.
---
## Appendix A — Surface Version Table
| Surface | Version | Notes |
| ------- | ------- | ----- |
| FCS/1 | v1-min | Canonical execution descriptors; governance captured in FCT/1. |
| FER/1 | v1.1 | Receipts enforce parity-first evidence, run_id dedup, typed logs, and RNG discipline (ADR-017). |
| FCT/1 | v1.0 | Certification transactions binding policy/intent/attestations with FER/1 sets. |
| FPD/1 | v1.0 | Publication digest linking FCT/1 to FER/1 receipts for federation replay. |
---
## Document History
* 0.2.1 (2025-10-26) — Phase Pack pointer updated; no semantic changes; archival preserves historical lineage per ADR-002.
* 0.2.2 (2025-10-26) — Promoted PH01 baseline to Approved; synchronized Phase Pack §1 anchors and closure snapshot.
* 0.2.3 (2025-10-27) — Added future scope alignment note pointing to FPS/1 and ADR-015; PH01 semantics remain unchanged.
* **0.2.4 (2025-11-14):** Added FR-014–FR-019 for FCS/1 composition, FER/1 receipts, and FCT/1 certification policies.
* **0.2.5 (2025-11-15):** Added FR-021 (formerly FR-020) enforcing acyclic FCS/1 composition and PCB1 arity validation.
* **0.2.6 (2025-11-19):** Registered FR-020 Deterministic Execution Envelope (Maat’s Balance) with timing evidence tags.
* **0.3.0 (2025-11-02):** Trimmed FCS/1 to execution-only (v1-min) under FR-014/FR-015; moved policy/intent/scope/role/authority to FCT/1 (FR-017); clarified registry admission behaviour and kept FER/1 unchanged.
* **0.3.1 (2025-11-21):** Updated FR-016 to require parity-first FER/1 receipts with executor sets, parity vectors, and FR-020 aligned timestamps.
* **0.3.2 (2025-11-22):** Registered FR-022 Federation Publication Digest (FPD/1) requirement tying FCT/1 publications to single-digest evidence and canonical logging.
* **0.3.4 (2025-11-07):** Recorded FER/1 v1.1 requirement for Phase 04 and added surface version table.
* **0.3.5 (2025-11-08):** Registered PH04 linkage & semantic placeholder requirements (FR-028…031).
* **0.3.6 (2025-11-09):** Promoted FR-028…031 to normative linkage requirements with CRS/1 validator enforcement.
* **0.3.7 (2025-11-08):** Finalized FR-028…031 with CRS/1 immutability, GS/1 linkage, and certification coverage.
* **0.3.8 (2025-11-09):** Promoted FR-028…FR-031 for concept-native domain and publication validation.
* **0.3.9 (2025-11-09):** Documented operational linkage: router endpoints, deterministic `/links`, and parent-required publish policy guidance.
* **0.3.10 (2025-11-11):** Registered FR-030 stateless, content-anchored FPD feed pagination requirement.
* **0.3.11 (2025-11-09):** Extended FR-031 with WT/1 intake endpoints, validation, and evidence log references.
* **0.3.12 (2025-11-20):** Tightened FR-031 with `wt.pubkey` bindings, signature preimage exclusion, lineage/policy errors, and
expanded WT/1 vector evidence coverage.
* **0.3.13 (2025-11-21):** Updated FR-031 for `has_pubkey` bindings (`ERR_WT_KEY_UNBOUND`), intent registry enforcement (`ERR_WT_INTENT_UNREGISTERED`), lineage policy rejection (`ERR_WT_PARENT_REQUIRED`), and expanded WT/1 vectors `TV-WT-001…009`.
* **0.3.14 (2025-11-22):** WT/1 intake and SOS/1 compat overlays proven with PH04-M4/M5 audit evidence.
* **0.3.15 (2025-11-22):** Recorded ADR-025/026 compat path requirements and evidence anchors for FR-031.
* **0.3.16 (2025-11-23):** Compat lane now enforces ADR-025/026 validators (MPR/1 hash triple, IER/1 replay) with updated evidence surfaces.
* **0.3.17 (2025-11-24):** Added FR-032–FR-034 for CT/1 replay determinism, numeric stability, and header integrity (ADR-027/028).
* **0.4.0 (2025-11-11):** Added FR-BS-001…005 for ByteStore identity, atomic durability, SA/PA isolation, COR round-trip, and streaming determinism linked to DDS §11 / ADR-030.

2
vendor/amduat vendored

@ -1 +1 @@
Subproject commit b7a0ee888d2b7502404723c91dc45309090bf461 Subproject commit 0fc1fbd980292fda121834ad5672950a5449c840