컴파일 파이프라인(개요)
이 장에서는 Go 컴파일러의 내부 동작 원리를 자세히 설명하며, 추상적인 YAML이 컴파일 파이프라인, 중간 표현(IR) 그래프, WebAssembly(Wasm) 실행 소켓을 거쳐 물리적 구성으로 변환되는 방식을 정의합니다.
컴파일 파이프라인과 실행 흐름
Aggrega는 하드코딩된 오케스트레이션 로직이 아니라 엄격한 고정 순서의 AOT(Ahead-of-Time) 컴파일러 파이프라인을 실행합니다. aggrega build로 트리거된 컴파일러는 물리적 아티팩트를 렌더링하기 전에 아키텍처를 평가하도록 평탄한 그래프를 격리된 WebAssembly(Wasm) 소켓 사이로 전달합니다.
Wasm 소켓은 임베디드 호스트(Wazero 엔진 위의 Extism 툴킷)에서 실행되며, 플러그인에 런타임 접근 기능(네트워크, 파일 시스템, 벽시계 시간, 환경, 표준 I/O)을 일절 허용하지 않는 AOT 순수성 방화벽 뒤에 있으므로 플러그인은 결정적이고 사전 컴파일된다는 보장을 깨뜨릴 수 없습니다. 호스트는 publishing-linter를 대역 외에서 aggrega lint를 통해 실행합니다. 아래에 설명하는 대역 내 게이트, 즉 토폴로지 구성 시 거버넌스 소켓의 label-transform 역할과 정적 분석 시 IR-verdict 역할, 그리고 렌더링을 마무리하는 플러그인 파이프라인은 모든 빌드에서 실행됩니다. 거버넌스 역할은 워크스페이스가 그 역할에 플러그인을 연결한 곳에서 실행되고, 플러그인 파이프라인은 단계를 선언하는 모든 Recipe에 대해 실행됩니다. 각 파이프라인 단계의 현황은 언어 현황에서 추적합니다.
파이프라인은 전적으로 메모리 내에서 엄격한 고정 순서로 실행됩니다.
해석 — 리졸버와 구문 검증기
- 메커니즘: 상속 병합, Go 템플릿 보간, JSON Schema 2020-12 검증.
- 동작: CLI는 요청된 모든 엔티티(Components, Features, Releases)를 가져옵니다. 먼저 이 정의들에
extends키워드가 있는지 확인합니다. 카탈로그 엔티티의 경우 YAML 메타데이터를 깊은 병합하며, 두 종류는 데이터 기둥에서 갈라집니다. Feature의schema:는 JSON Schema 2020-12 합성 방식으로 기반의 것과 합성되는 반면, 확장하는 Component는 구조만 합성하고(첨부 슬롯, 토폴로지 소켓, 자체 주입 허용 목록, 명명된 어설션) 기반의schema:블록은 기반이 작성한 그대로 받습니다. 확장하는Release도 같은 규칙으로 접힙니다. 자식의 값이 키 단위로 우선하며, 첫 번째 나눌 수 없는 값(스칼라, 리스트, 템플릿)까지 내려가 그 값은 통째로 교체되고, 자식이null로 작성한 키는 제거됩니다. 따라서 작성 표면 전체가 이어집니다. 즉 컴포넌트별infra와 Feature 첨부를 포함한 경계 트리,parameters블록, 어노테이션, Manifest 포인터가 이어지지만, 식별 정보와 출처는 Release마다 고유하므로metadata필드는 어느 것도 이어지지 않습니다. 다음으로 세 하위 단계로 메모리 내 보간을 수행합니다. Aggregate의 타입이 지정된parameters:선언에 대한 매개변수 계약 검증, 해석된 값을 주변values:문자열에 보간, 그리고 모든 값 템플릿 컨텍스트에서.parameters맵을 철회하여 운영자가 작성한 경로 템플릿에서만 읽을 수 있도록 남기는 것입니다. 마지막으로 해석된infra블록을 대상 컴포넌트 페이로드에 주입합니다. 청사진이 완전히 구체화되면 컴파일러는 카탈로그의 통합schema:선언(축약형 또는 전체 JSON Schema 2020-12)을 사용해 개발자의values및infra구성을 로컬에서 엄격하게 검증합니다.- Release Feature 스키마 검증: Release를 통해 첨부된 Features(경계 전체 및 컴포넌트별 모두)는 이 단계에서 해당 카탈로그 엔티티에 대해 해석됩니다. 컴파일러는 카탈로그 해석 직후 Release가 제공한
infra블록을 각 Feature의schema:선언에 대해 검증하여, 토폴로지가 구축되기 전에 타입 안전성을 보장합니다. - 어노테이션 기반 Feature 확장 하위 단계: Manifest 해석, Recipe/Provider 바인딩, Manifest 바인딩 대상 검증(
mappings.features.annotations.<key>.maps아래 선언된 경로가 참조된 Feature의spec.schema에 존재하는지) 이후, 컴파일러는 토폴로지 빌더 전에 어노테이션 확장 하위 단계를 실행합니다. 이 하위 단계는 Release 경계를 바깥에서 안쪽으로, Aggregate 서브시스템을 바깥에서 안쪽으로 순회하며 캐스케이드 + 오버라이드 + null 옵트아웃 병합으로 컴포넌트별 유효 어노테이션 집합을 계산합니다. 각 어노테이션 값을 YAML로 파싱하여 스칼라, 구조화 값 또는 null로 만들고, 각 값(스칼라 또는 하위 키별 구조화 값)을 Manifest 바인딩의maps선언을 통해 대상 Feature 스키마 기둥으로 라우팅하면서 측면 대 기둥 규칙을 적용합니다(Aggregate 측은maps.values를, Release 측은maps.infra를 발화). 또한 Feature의spec.schema에 대해 리프별 타입을 검증하고, IR 그래프가origin: annotation으로 표시하는 합성 Feature 첨부를 주입합니다. 스키마는 빌드당 한 번 컴파일되어 캐스케이드 순회 간에 재사용됩니다. 확장은 바인딩 대상 검증 후, 토폴로지 구성 전에 실행되므로, 후속 단계는 합성 첨부를 명시적 첨부와 구조적으로 동일하게 취급합니다(출처 검사를 통하는 경우는 예외). 바인딩 형태, 캐스케이드 의미론, 측면 간 합성 규칙은 13-catalog-and-registry.md §“어노테이션 기반 Feature 확장”과language-reference/providers/well-known-annotations.md를 참조하십시오.
- Release Feature 스키마 검증: Release를 통해 첨부된 Features(경계 전체 및 컴포넌트별 모두)는 이 단계에서 해당 카탈로그 엔티티에 대해 해석됩니다. 컴파일러는 카탈로그 해석 직후 Release가 제공한
토폴로지 구성 — 토폴로지 빌더와 변형 게이트
- 메커니즘: AST 확장 + 거버넌스 소켓의
label-transform역할. - 동작: 컴파일러는 검증된 컴포넌트에서 명시적으로 선언된
uses블록을 네이티브로 읽어 그래프의 노드 사이에 토폴로지 간선을 결정적으로 그리며,values블록은 완전히 불투명하게 둡니다. 그런 다음 변형 게이트를 평가하여, 그래프의 투영(각 노드의 레이블과 그 인스턴스가 선언한values로, 컴파일러는 이를 읽지 않고 넘깁니다)을 Release의 이름 및 환경과 함께label-transform역할에 첨부된 거버넌스 플러그인에 전달합니다. 플러그인은 컨텍스트를 평가하고 JSONPatch를 반환하여 그래프에 동적으로 자동 태그를 붙입니다(예: Release의 환경에 따라compliance.aggrega.ai/data-class: restricted레이블을 주입하거나, 데이터베이스가 선언한 확장에 따라datastore.aggrega.ai/engine: vector를 주입). 패치는 레이블에만 적용됩니다.
그래프 확정
- 메커니즘: 정규화.
- 동작: 컴파일러는 토폴로지 빌더가 그린 명시적 토폴로지 간선을 보존하면서 평탄한 IR(중간 표현) 그래프를 확정합니다. 그런 다음 첨부된 Features와 그
values페이로드를 노드 ID로 매핑된 평탄한 딕셔너리로 정규화하여, 기능에 구애받지 않는 그래프를 검증에 대비시킵니다.- IR 페이로드 정규화: IR의 구조적 형태는 구성에 대한 단일 진실 공급원을 강제합니다. 토폴로지 계층은 그래프 구조(노드 식별 정보, 간선, 메타데이터 레이블)만 담고, 정규화된 구성 상태는 컴파일러가 후속 플러그인에 전달하는 별도의 메모리 내 딕셔너리에 있습니다. 구성을 변경하는 변형자는 한 곳에서만 변경하며, provider는 중복 저장으로 인한 불일치 위험 없이 정규화된 상태를 읽습니다.
정적 분석 — 정적 분석기와 검증 게이트
- 메커니즘: 토폴로지 순수성 검사 + 거버넌스 소켓의
ir-verdict역할. - Action: 컴파일러는 IR Graph에 대해 추상 정적 분석을 실행합니다. 먼저
usesSchema정의에서selector문자열을 추출하고, 네이티브 Go 레이블 매칭 엔진(Kubernetes 스타일의AND,in()을 통한OR,!=을 통한NOT의미 체계 지원)을 사용해 명시적으로 정의된 그래프 엣지 전반에서 이를 평가하여 선언된 소켓에 대한 노드 간 타입 안전성을 보장합니다. 애드혹 소켓, 즉 Aggregate 작성자가 이름을 붙였지만 카탈로그가 선언하지 않은 소켓의 엣지에는 카탈로그 항목이 없으므로 셀렉터도 없습니다. 따라서 이 검사가 평가할 대상도, 누락된 것도 없습니다. 각 엣지는 둘 중 어느 쪽인지를 기록하며, 애드혹 엣지가 전달할 수 있는 내용은 대신 대상이 선언한provides로 제한됩니다. 또한 Feature의appliesTo및appliesToAnyOf셀렉터를 평가하여 연결된 feature가 대상 component의 레이블과 호환되는지 확인하고, 채워진 각 attachment 슬롯의 자체selector를 그 슬롯을 채우는 Feature의 레이블에 대해 평가합니다. 둘째, 노드의 Component가 선언하는 모든 존재 의무(presence mandate), 즉 각features.aggrega.ai/requiredType.<label>어노테이션을 해당 노드의 최종 attachment 집합에 대해 평가합니다. 이 검사가 분석기에 속하는 이유는 분석기가 규칙의 두 절반, 즉 해석된 Component 엔티티의 어노테이션과 5-Tier 캐스케이드가 생성한 attachment 집합을 모두 보유하는 첫 번째 단계이기 때문입니다. 이 집합에는 Aggregate에 연결된 attachment, 서브시스템에 연결된 attachment, Release에 연결된 attachment, 어노테이션으로 확장된 attachment가 모두 똑같이 포함됩니다. 어떤 attachment로도 충족되지 않는 의무는 빌드를 중단시키며, 선언 형식이 잘못된 의무는 별도의 진단과 함께 중단시키므로 잘못된 선언이 충족된 요구 사항으로 읽히는 일은 없습니다. 셋째, Validation Gate를 실행하여 전체 그래프 구조(모든 노드, 엣지, 연결된 feature, 미리 계산된 DFS 경로 포함)를ir-verdict역할에 연결된 거버넌스 플러그인에 전달합니다. 기업의 사용자 정의 Wasm 정책이 토폴로지를 평가합니다. Wasm 플러그인이 실패 배열을 반환하면(예: 특정 프록시 feature 없이public노드에서restricted노드로 이어지는 연속 경로를 감지한 경우) 빌드가 중단됩니다.
렌더링
- Mechanism: 렌더링 전 가로채기(
injectMapping), 지연 바인딩(valuesMapping), Wasm 렌더링 소켓(pipeline). - Action: 최종 아티팩트 생성 단계는 고정된 순서로 실행되는 엄격한 시간 순서의 하위 단계로 나뉘며, 이로써 실행이 결정적으로 유지됩니다.
- Inject mapping(렌더링 전 가로채기): Go 컴파일러가 개발자의 추상
.context.inject계약을 해석합니다. 그런 다음 연결된 모든FeatureRecipes의injectMappingGo 템플릿을 엄격한 5-Tier Onion Model 실행 순서(Sub-Aggregate — 모듈 component 자체의 attachment, 그다음 그 모듈의 subsystem이 선언하는 attachment, 바깥에서 안쪽으로 → Root Aggregate component → Root Aggregate subsystem → Release boundary 바깥에서 안쪽으로 → Release component별)에 따라 실행합니다. 컴파일러는 결과 딕셔너리를 호출자의.context.inject메모리 파이프 위에 네이티브 방식으로 딥 머지합니다. 이를 통해 Base Recipe가 보기 전에 호출자의 환경 변수와 연결 문자열을 안전하게 재작성합니다. 매핑은 호출자 자신의inject:블록이나 그 연결 중 하나가 전달한 값을 재작성할 수 있습니다. 반면 다른 연결된 Feature가 자체 매핑이나 자체inject:블록을 통해 이미 전달한 키는 두 attachment의 이름을 밝히며 빌드를 중단시키므로, 실행 순서가 두 attachment의 값 중 하나를 결정하는 일은 없습니다. - Locals 프리앰블: 어떤
provides템플릿이 실행되기 전에, 컴파일러는 Recipe의.locals항목을 작성된 순서대로 평가합니다. 각 항목은 자체 완결된 노드 로컬 컨텍스트, 즉.context.instance_id,.values,.infra및 지금까지 해석된 같은 블록의 항목에 대해 평가되며,.context.inject나.context.uses는 포함되지 않습니다. 따라서 항목은 자신보다 위에 정의된 형제 항목을 읽을 수 있으며 그 형제 항목의 해석된 값을 받습니다. 한 항목이 다른 항목을 읽는 경우 작성 순서는 계약의 일부이며, 참조를 해석하기 위해 블록의 순서를 바꾸는 일은 없습니다. locals를 먼저 해석하기 때문에provides템플릿이.locals를 읽을 수 있습니다. Recipe의.source템플릿은 해당 locals가 해석된 후 같은 컨텍스트에 대해 평가되므로,.locals를 Recipe의 템플릿 전반에서 약칭으로 재사용할 수 있고 작성자는 boundary별로.source(차트 버전, 경로, 레지스트리)를 매개변수화할 수 있습니다. - 기본 렌더링(base Recipe
valuesMapping): 컴파일러는 Base Recipe의valuesMapping템플릿을 평가합니다. 템플릿은.context.inject파이프에서 가로챈 문자열(inject mapping 중에 재작성됨)을 읽고, 결과 값 딕셔너리는 Recipe의capability가 지정하는 provider에 전달되어(helm 및 helm-chart provider는 모두 Helm을 통해 렌더링합니다) 기본 인프라 아티팩트를 렌더링합니다. - Workload 파싱 및 검증:
workload:를 선언하는 Recipe, 즉 인라인 블록 콘텐츠이거나 파일을 지정하는workload: { $import: <path> }를 선언하는 Recipe는 해당 문서가 노드의 렌더 컨텍스트에 대해 템플릿으로 평가된 후 YAML로 파싱되어 Workload 형태가 되고 검사됩니다. 렌더링된 바이트는 Workload 스키마에 대해 검증되고, 디코딩된 값도 같은 스키마에 대해 검증됩니다(바이트에는 디코딩이 버리는 키가 포함되고, 디코딩은 빈 값으로 제공된 필드를 생략하므로 각각은 다른 쪽이 볼 수 없는 것을 거부합니다). 모든attachments항목은 바인딩된 Component의featuresSchema가 선언한 슬롯에 대해 검사되고, 모든 리소스 참조는 그것이 지정하는 슬롯의 해석된provides에 대해 검사됩니다. 여기서 실패하면 빌드가 중단됩니다. 파싱된 Workload는 템플릿 컨텍스트에.workload로 배치되므로, 같은 노드에서 나중에 평가되는 템플릿이 이를 읽을 수 있습니다. - Artifacts 평가: Recipe가
artifacts:아래에 선언하는 모든 항목(인라인 콘텐츠 또는 해당 항목 자체의$import:가 지정하는 파일)은 읽히고, 템플릿으로 파싱되고, 전체 템플릿 컨텍스트에 대해 평가되며, 빌드의 출처 정보를 갖습니다. 결과 프로젝션은 provider에 전달되며, provider가 출력 형식, 출처 정보가 기록될 위치, 출력 경로 및 최종 바이트를 결정합니다. 출력된 각 파일은 어떤 작성 형식에서 왔는지를 기록하므로, 파일 이름 충돌 시 모든 기여자를 밝힐 수 있습니다. - Workload 합성: 파싱된 Workload는 Recipe의
capability가 지정하는 provider에 전달되며, provider는 이를 해당 provider의 네이티브 리소스로 변환합니다.workload:를 선언하지 않는 Recipe는 여기서 합성할 것이 없으며, 그 파일은 대신 source 렌더링에서 나옵니다. - Feature 렌더링(FeatureRecipe 리소스 생성): 바인딩된 FeatureRecipe가 자체
source,workload,artifacts및/또는valuesMapping을 가지는 노드의 모든 attachment — ServiceMonitor, NetworkPolicy, 사이드카 ConfigMap 또는 자격 증명 전달 리소스와 같은 보조 매니페스트에 사용되는 리소스 생성 패턴 — 는 inject mapping이 따르는 것과 같은 5-Tier Onion Model 순서로 한 번의 패스에서 평가됩니다. 하나의 attachment 집합에 대해 하나의 순서가 있습니다. 운영용 Feature와 자격 증명 Feature는 같은 경로를 거치며, 둘의 차이는 각 FeatureRecipe가 무엇을 내보내는가에 있습니다. 각 attachment의.values와.infra는 해당 attachment 자체의 스코프로 교체되고, base Recipe의 평가된.locals를 상속하며,.attachment_name은 렌더링 중인 인스턴스의 이름을,.provides는 소비자가 읽는 것과 같은 attachment 자체의 해석된 provides를 담습니다. 결과 values 딕셔너리는 FeatureRecipe 자체의 capability가 지정하는 provider에 전달되고, 렌더링된 파일은 두 좌표 — Feature가 연결된 component, 그다음 연결된 이름 — 를 가진 채 boundary의 출력에 추가되므로, 하나의 Feature 이름이 여러 component에 연결되어도 각각이 분리되어 유지됩니다. 이 좌표가 어떤 형태를 취하는지는 호스트 provider 자체의 레이아웃에 따릅니다. 대상이 각 기여자에게 고유한 위치를 부여하는 경우에는 component 자체 디렉터리 옆의<component>--<instance>/디렉터리가, 디렉터리 바로 안에 있는 파일만 읽는 경우에는<component>--<instance>--파일 이름 접두사가 됩니다. inject 전용 FeatureRecipes —injectMapping만 가지며 inject mapping 단계에서 이미 처리된 것 — 는 여기서 건너뜁니다. 앞선 하위 단계와 마찬가지로 feature 렌더링은 한 번에 하나의 component에 대해 실행되므로, attachment는 보통 연결된 component 직후에 평가됩니다. FeatureRecipe가readsCallerRenderFacts: true또는readsTargetRenderFacts: true를 선언한 attachment는 대신 모든 component와 둘 중 어느 것도 선언하지 않은 모든 attachment가 렌더링된 뒤에 평가됩니다 — 따라서 그 시점에는 호스트에 연결하는 각 component와 호스트가 연결된 각 component가 모두 렌더링된 상태입니다 — 그리고 그 출력은 원래 위치했을 곳에 놓입니다. - 플러그인 파이프라인(Wasm 단계 실행): 컴파일러는 Recipe의
pipeline배열을 읽고 선언된 순서대로 단계를 실행합니다. 각 단계에 지정된 Wasm 플러그인을 노드의 렌더링된 문서에 대해 디스패치하고, 단계가 반환한 RFC 6902 JSON Patch 연산을 해당 연산이 가리키는 문서에 적용하며, 단계의 부수 효과를 그 옆에 함께 내보냅니다. 이것이 Envoy 사이드카 주입이나 secret VolumeMount 마운트 같은 정밀한 변경을 뒷받침하는 표면입니다.when:게이트가 거짓 값으로 렌더링되는 단계는 통과 처리로 건너뛰어, 다음 단계를 위해 문서 집합을 변경하지 않은 채로 둡니다. 각 단계의pluginURI는 실행 전에 lockfile이 다이제스트로 고정한, 검증된 아티팩트 바이트로 해석됩니다. FeatureRecipe의pipeline단계도 같은 방식으로 실행되며, attachment 자체의 렌더링된 문서와, component 스코프 attachment의 경우 호스트 component의 문서를 함께 대상으로 합니다.
- Inject mapping(렌더링 전 가로채기): Go 컴파일러가 개발자의 추상
세 가지 Recipe 입력 종류 모두 컴파일러에 도달합니다. source: + valuesMapping:은 base 렌더링을 통해, workload:는 workload 파싱과 workload 합성을 통해, artifacts:는 artifacts 평가를 통해 도달합니다. 특정 provider에 이 중 어떤 것을 전달할 수 있는지는 하위 단계마다 결정되지 않습니다. 이는 렌더 디스패치 이전에 provider 자체가 선언한 계약에 따라 노드마다 한 번 확정되므로, 바인딩된 provider가 받아들이지 않는 입력 종류를 가진 Recipe는 렌더링 도중이 아니라 그 시점에 거부됩니다. 세 가지 입력 종류의 구성 모델, Workload 종류, Artifacts 메커니즘은 16-recipe-input-composition.md를, 어떤 provider가 어떤 종류를 받아들이는지는 언어 현황을 참조하십시오.
GitOps 네이티브 출력
출력이 어떻게 적용되는지에 대해 엄격하게 주관이 없는 상태를 유지하기 위해, 렌더링 플러그인은 생성된 아티팩트를 깔끔하고 boundary별로 격리된 디렉터리 구조(예: dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/)로 출력합니다. 이를 통해 외부 GitOps 컨트롤러(ArgoCD나 Flux 등)는 Aggrega 컴파일러가 라이브 클러스터 API 자격 증명을 전혀 필요로 하지 않고도 인프라를 동기화하고 적용할 수 있습니다.
graph TD
subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
direction TB
A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
end
graph LR
E["Rendering"]
E -->|"Stringified Artifacts"| F["Helm Charts"]
E -->|"Stringified Artifacts"| G["Docker Compose"]
E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
E -->|"Stringified Artifacts"| I["Terraform Configuration"]
E -->|"Stringified Artifacts"| J["CloudFormation Templates"]
인프라 소스 맵
Aggrega는 약 30줄의 Aggregate.yaml을 수천 줄의 물리적 JSON 또는 YAML 구성으로 컴파일합니다. 실행 중인 리소스를 소스까지 추적할 방법이 없다면, “main.tf.json 4,032번째 줄”의 오류를 디버깅할 때 개발자가 매핑을 수동으로 재구성해야 합니다. Aggrega의 렌더링 플러그인은 provider의 네이티브 메타데이터 표면 — Kubernetes의 metadata.labels 및 metadata.annotations, Terraform의 출처 주석, 그리고 provider별 동등한 관례 — 에 추적 식별자를 병합하여 이 문제를 해결하므로, 렌더링된 각 객체는 그 출처인 소스를 가리키는 포인터를 지닙니다. aggrega.ai/compiler-version 레이블(governance-and-compliance §5에 설명됨)은 이 계열의 추적 키 중 하나입니다. 스탬프는 그 옆에 aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri, aggrega.ai/environment도 담으며, helm, helm-chart, compose, terraform, cloudformation provider가 각각 이를 내보냅니다. helm-chart provider는 chart 자체의 템플릿을 변경 없이 복사하므로, Recipe가 chart에 추가하는 템플릿 파일에 이를 내보냅니다.
스탬프에는 기능의 출처나 카탈로그 유형을 식별하는 키가 없습니다.
컴파일러에는 두 가지 디버그 수단이 더 포함되어 있습니다. aggrega build --trace는 각 노드의 중간 상태를 패스별로 .trace/(dist/ 옆)에 기록하여, Recipe 작성자가 각 단계가 무엇을 받고 무엇을 만들었는지 살펴볼 수 있게 합니다. 또한 빌드를 중단하는 진단은 실패에 해당 작성 표면이 있는 경우 그 범주(DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR 등)를 지니므로 올바른 작성자를 가리킵니다. 실패한 생성 매니페스트 필드를 그것을 만든 템플릿 줄까지 추적하는 오류는 컴파일러에 포함되지 않습니다.
검증기 파이프라인
해석 단계의 스키마 검증 단계는 검증기 파이프라인을 기반으로 합니다. 이 파이프라인은 엔티티 스펙 콘텐츠(compact form, JSON Schema YAML 또는 혼합)를 리프별 출처 정보를 갖춘 단일 JSON Schema 2020-12 문서로 변환한 다음, 개발자가 작성한 인스턴스 콘텐츠를 그 문서에 대해 검증합니다. 다섯 단계가 순수 변환으로 순서대로 실행되며, 각 단계는 선언된 입력에 대한 결정적 함수입니다.
1단계 — compact form 컴파일. 컴파일러는 schema:, parameters: 및 SchemaLibrary 콘텐츠의 YAML 트리를 순회하고, 노드별로 분기(compact form 리프, JSON Schema YAML, $ref: 참조, 합성)하여 해석된 JSON Schema 2020-12를 출력합니다. compact form과 JSON Schema YAML은 $jsonschema: 탈출구를 통해 어느 노드 경계에서든 섞일 수 있으며, 컴파일러는 트리를 순회하며 노드별로 분기하는 방식으로 혼합된 경우를 처리합니다. 이 변환은 순수 함수입니다. 같은 compact form 입력은 항상 같은 JSON Schema 출력을 만듭니다. 키워드 어휘는 language-reference/vocabulary/compact-form-authoring.md를 참조하십시오.
2단계 — spec.templates 및 $instantiate: 해석. 템플릿 참조로 작성된 SchemaLibrary 항목에 대해, 컴파일러는 $args:와 함께 $instantiate:를 호출하는 모든 라이브러리 항목을 순회하고, 매개변수 값을 리터럴 스칼라 치환으로 대입하여 구체적인 스키마 항목을 만듭니다. 치환은 라이브러리 로드마다 한 번 실행되며, 해석된 항목은 캐시됩니다. 라이브러리 엔티티의 작성 형태는 language-reference/entities/schemalibrary.md를 참조하십시오.
3단계 — 문서 간 $ref: 확장. $ref:(식별자 형식 <Library>#/schemas/<entry>)를 통한 SchemaLibrary 참조에 대해, 컴파일러는 해석 스택 스레딩을 통해 컴파일 시점에 참조 체인을 순회하며, 참조된 콘텐츠는 소비자의 스키마에 인라인됩니다. 이 확장은 순환 감지(순환은 체인을 명시하는 오류와 함께 빌드를 중단합니다), 위치가 아닌 식별자 가드레일(레지스트리 호스트를 포함한 참조는 식별자 형식으로 안내하며 중단됩니다 — 참조는 물리적 위치가 아닌 식별자로 라이브러리를 가리킵니다), 단일 출처 합성($ref: 블록은 순수 참조만 허용하며, 소비자 측 재정의는 JSON Schema의 allOf:로 합성됩니다)을 유지합니다. 해석 의미론은 language-reference/vocabulary/cross-document-ref.md를 참조하십시오.
4단계 — featuresSchema:를 위한 브리지 합성. 컴파일러는 각 엔티티의 featuresSchema: 콘텐츠를 작성 순서대로 순회하고, 각 attachment 슬롯에 바인딩될 수 있는 채움의 형태를 기술하는 JSON Schema 조각을 출력합니다. inject 허용 목록을 선언한 슬롯에는 x-aggrega-inject: 확장 키워드가 붙습니다. 이 조각은 개발자용 schema: 콘텐츠에 병합되지 않고, 작성된 attachment 블록에 대해 독립적으로 컴파일되고 검사됩니다. 확장 키워드는 JSON Schema 검증이 무시하는 메타데이터이며, 이후 어떤 단계도 이를 조각에서 다시 읽지 않습니다. 슬롯의 허용 목록이 필요한 검사는 슬롯을 읽습니다. usesSchema: 소켓 테이블은 어떤 조각으로도 투영되지 않습니다. 소켓의 selector:와 inject:는 Architect가 작성한 타입이 지정된 YAML로 읽히며, 소켓의 엣지별 valueSchema: / infraSchema:는 독립적으로 컴파일됩니다. 이 합성은 입력에 대한 순수 함수입니다.
5단계 — 출처 정보를 갖춘 사용자 정의 병합기. extends:를 선언한 엔티티에 대해, 컴파일러는 상위 체인을 순회합니다. 상위의 해석된 JSON Schema가 기반이 되고, 하위의 재정의가 그 위에 적용됩니다. 해석된 스키마의 모든 리프는 리프별 출처 태그(파일 경로, 줄 번호, 상위/하위 출처)를 가집니다. 병합기의 출력은 검증기 엔진이 소비하며, 검증기 엔진은 수정되지 않은 서드파티 JSON Schema 2020-12 적합성 구현에 순서가 정해진 결과 출력을 위한 결정적 순회기를 덧씌운 것입니다.
다섯 단계는 검증기 엔진이 스키마를 보기 전에 실행됩니다. 엔진은 해석된 단일 JSON Schema 2020-12 문서와 개발자의 인스턴스 콘텐츠를 받아 검증 보고서를 만듭니다. 오류 포매터는 출처 태그를 참조하여 소스 위치를 명확히 밝히는 사용자용 진단을 출력합니다. 여기에는 Feature가 직접 작성하지 않고 기반에서 상속한 제약 조건의 원본 파일도 포함됩니다.
검증기 파이프라인은 각 페이로드가 처음으로 완성되는 지점에서 실행됩니다. 해석 중 컴포넌트의 values와 infra, 토폴로지 구성이 하위 aggregate를 가져올 때 그 컴포넌트, 그리고 그래프 최종화 시점의 첨부 페이로드입니다. 따라서 스키마 검사 결과는 정적 분석이 셀렉터를 평가하기 전, 그리고 어서션 평가 전에 빌드를 중단하며, 덕분에 어서션 템플릿은 검증된 페이로드에 의존할 수 있습니다.
파이프라인 전반의 결정성 보존
컴파일 파이프라인의 모든 단계는 결정적 출력 불변식(Deterministic Output Invariant)을 보존합니다. 동일한 소스 파일, 동일한 lockfile, 동일한 컴파일러 버전이 주어지면 빌드는 바이트 단위로 동일한 출력을 생성합니다. 이 불변식은 기반이 되는 속성입니다. lockfile의 콘텐츠 주소 지정에는 안정적인 아티팩트 다이제스트가 필요하고, 재현 가능한 빌드에는 개발자 A의 노트북에서 작성한 release가 개발자 B의 노트북과 CI에서 동일한 출력으로 컴파일되어야 하며, diff 검토 가능성을 위해서는 소스 변경이 컴파일된 출력에서 유일한 변경으로 나타나야 합니다.
결정성은 모든 변환이 따르는 소수의 원칙으로 보존됩니다.
- 고정된 순회 순서. Go의 기본 map 순회는 무작위이므로, 맵 형태 YAML에 대한 모든 순회는 고정된 순서로 진행됩니다. 컴파일러는 대부분의 단계(compact form 컴파일러, 병합기,
spec.templates해석기, 오류 포매터, YAML 직렬화기)에서 순회 전에 정렬합니다. 반면 attachment 슬롯 투영은 작성자의 순서를 그대로 유지하므로, 슬롯 테이블의 속성 순서는 작성된 순서와 같습니다. - 시간 정보 미포함. 컴파일은 출력에 타임스탬프를 포함하지 않습니다. 오후 2시의 빌드와 오전 2시의 빌드는 동일한 아티팩트를 생성합니다. 병합기의 출처 메타데이터는 file:timestamp가 아니라 file:line을 사용합니다.
- 워크스페이스 상대 경로. 해석된 출력의 모든 경로는 워크스페이스 기준 상대 경로입니다. 경로 해석 계층은 경로가 출력에 들어가기 전에 정규화합니다.
- 무작위 소스 및 외부 상태 없음. 변환은 선언된 입력(엔티티 콘텐츠, 부모 체인, lockfile)에 대한 순수 함수입니다. 외부 상태는 해석 중(OCI 아티팩트 가져오기)에만 참조되며, 해석된 콘텐츠는 다이제스트로 콘텐츠 주소가 지정됩니다.
- 정규 YAML 직렬화. 출력은 하나의 입력에 대해 하나의 고정된 형태로 기록됩니다. 모든 실행에서 모든 깊이에 같은 키 순서를 사용하고, 배열과
enum:배열은 입력 순서를 유지하며, 2칸 들여쓰기, Unix LF 줄 끝, YAML이 허용하는 곳에서는 따옴표 없는 문자열,true/false불리언 형식을 사용하고, 없는 필드의 null은 생략합니다. $defs:알파벳순. 스키마의$defs:항목은 해석된 JSON Schema에서 알파벳순 키 순서로 출력됩니다.$defs:는 개념적으로 순서 있는 목록이 아니라 사전이며, 알파벳순은 소스를 재구성해도 diff를 예측 가능하게 만듭니다.- 병렬 처리는 출력에 드러나지 않습니다. 컴파일러는 독립적인 단위를 병렬화할 수 있습니다(서로 다른 엔티티는 동시에 컴파일될 수 있습니다). 병렬 결과는 직렬화 전에 결정적인 구조(예: 엔티티 이름순 정렬)로 수집됩니다.
컴파일러의 엔드투엔드 테스트는 하나의 테스트 안에서 각 픽스처를 여러 번 컴파일하고, 모든 실행이 바이트 단위로 동일한 내용의 같은 파일을 내보내는지 검증합니다. 컴파일을 반복해야만 맵 순회 순서 누출이나 정렬되지 않은 집합에 대한 순회를 잡아낼 수 있습니다. 이러한 문제는 대부분의 실행에서는 안정적인 출력을 내다가 가끔 달라집니다. 이 테스트는 컴파일러의 나머지 테스트 스위트와 함께 실행됩니다.
결정적 출력 불변식은 빌드 시점에 적용됩니다. 동일한 소스 파일 + 동일한 lockfile + 동일한 컴파일러 버전이 주어지면 바이트 단위로 동일한 출력이 나옵니다. lock 시점의 대응 속성(동일한 소스 파일 + 동일한 레지스트리 상태가 주어지면 동일한 lockfile)은 더 약합니다. 레지스트리는 변경 가능하므로(새 버전이 게시될 수 있고, sidecar가 추가될 수 있으며, component별 메타데이터가 변할 수 있음), 같은 소스 파일에 대해 서로 다른 시점에 실행한 두 lock 호출은 서로 다른 lockfile을 생성할 수 있습니다. 이것이 바로 lockfile의 목적이며, npm, Cargo, Go의 관례를 따릅니다. 새로 만든 lockfile로부터 빌드는 결정적인 출력을 생성합니다. 이 두 시점의 분리 덕분에 레지스트리 측 변경 가능성을 감내할 수 있습니다. 시점 T2에 게시된 sidecar는 다음 lock 호출을 바꾸지만, T1에 생성된 lockfile에 대한 빌드는 바꾸지 않습니다.