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

9.8 KiB
Raw Blame History

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.