From 75a9af30657f96c0d44cb11946bb3378f267c920 Mon Sep 17 00:00:00 2001 From: Carl Niklas Rydberg Date: Sat, 17 Jan 2026 00:07:10 +0100 Subject: [PATCH] add some more specs --- tier1/dds.md | 909 ++++++++++++++++++++++++++++++++++++++++++++++++++ tier1/fcs.md | 223 +++++++++++++ tier1/fls.md | 58 ++++ tier1/fps.md | 121 +++++++ tier1/srs.md | 518 ++++++++++++++++++++++++++++ vendor/amduat | 2 +- 6 files changed, 1830 insertions(+), 1 deletion(-) create mode 100644 tier1/dds.md create mode 100644 tier1/fcs.md create mode 100644 tier1/fls.md create mode 100644 tier1/fps.md create mode 100644 tier1/srs.md diff --git a/tier1/dds.md b/tier1/dds.md new file mode 100644 index 0000000..77b7da2 --- /dev/null +++ b/tier1/dds.md @@ -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/ + └─ / + ├─ 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 | 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 | One or more FER/1 CIDs | +| `fct.authority_role` | ENUM | ADR-010C role | +| `fct.domain_scope` | ENUM | ADR-010B scope | +| `fct.intent` | SET | ADR-010 intents | +| `fct.constraints` | LIST | Optional constraint set | +| `fct.attestations` | LIST | 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 | 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 | 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=&limit=` 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=&after=&limit=` 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 *(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-` 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. diff --git a/tier1/fcs.md b/tier1/fcs.md new file mode 100644 index 0000000..6f49070 --- /dev/null +++ b/tier1/fcs.md @@ -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:"`, where `` 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. + +--- diff --git a/tier1/fls.md b/tier1/fls.md new file mode 100644 index 0000000..e7edd28 --- /dev/null +++ b/tier1/fls.md @@ -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. diff --git a/tier1/fps.md b/tier1/fps.md new file mode 100644 index 0000000..2540ee4 --- /dev/null +++ b/tier1/fps.md @@ -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. diff --git a/tier1/srs.md b/tier1/srs.md new file mode 100644 index 0000000..20967e0 --- /dev/null +++ b/tier1/srs.md @@ -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/-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=&limit=`) 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. diff --git a/vendor/amduat b/vendor/amduat index b7a0ee8..0fc1fbd 160000 --- a/vendor/amduat +++ b/vendor/amduat @@ -1 +1 @@ -Subproject commit b7a0ee888d2b7502404723c91dc45309090bf461 +Subproject commit 0fc1fbd980292fda121834ad5672950a5449c840