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