# 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. ---