언어의 상태
이 페이지는 Aggrega의 어떤 기능 영역이 현재 사용 가능한지, 어떤 영역이 문서화되어 있으나 아직 컴파일러가 처리하지 않는지, 어떤 영역이 향후 반복에서 계획되어 있는지에 대한 표준 참조 문서입니다. 언어 전반의 준비 상태를 한곳에 모아 보여 줌으로써 영역별 장을 보완합니다.
이 페이지를 참조하는 독자는 두 부류입니다. 처음 작성하는 작성자는 익숙하지 않은 영역을 대상으로 작성하기 전에 이 페이지를 확인하여 해당 영역이 현재 렌더링된 출력을 생성하는지 확인합니다. 참조를 찾는 독자는 사용 중인 영역이 예상과 다르게 동작할 때 이 페이지를 확인합니다. 예를 들어 YAML은 검증을 통과하지만 출력이 생성되지 않는 경우, 해당 영역의 상태를 가장 먼저 찾아볼 곳이 이 페이지입니다. 다시 방문한 독자도 지난번 읽은 이후 상태 레이블이 바뀐 영역을 파악하기 위해 이 페이지를 참조합니다. 영역별 장과 엔터티 참조는 해당 영역이 어떻게 동작하도록 설계되었는지를 설명하며, 이 페이지는 그것이 이미 동작하는지를 설명합니다.
상태 분류
이 페이지의 모든 언어 표면에는 네 가지 상태 레이블 중 하나가 붙습니다.
-
available. 스키마가 해당 표면을 받아들이고, 컴파일러가 이를 소비하며, 동작이 문서화된 계약과 일치합니다.
available표면을 사용하는 작성자는 문서화된 계약대로의 동작을 얻습니다. -
accepted but inert. 스키마가 해당 표면을 받아들이므로 이를 사용해 작성하면 검증을 통과하지만, 컴파일러는 아직 이에 따라 동작하지 않습니다.
accepted but inert표면을 작성하면 구문상 유효한 빌드가 만들어지지만 해당 표면에 대한 렌더링 효과는 없습니다. 컴파일러가 비활성 표면을 지목하는 경고를 내보낼 수도 있고(권장되는 패턴), 현재 일부 표면은 경고 없이 조용히 건너뜁니다. 아래의 섹션별 항목에서 구체적인 동작을 밝힙니다. -
accepted but blocked. 스키마가 해당 표면을 받아들이므로 이를 사용해 작성하면 검증을 통과하지만, 컴파일러는 이를 렌더링하지 않고 빌드를 중단합니다.
accepted but blocked표면을 사용해 작성하면 렌더링 시점에 대신 무엇을 작성해야 하는지 밝히는 명시적인 오류와 함께 실패합니다. 차단은 영구적일 수 있습니다. 이 경우 작성된 내용은 컴파일러가 작성자를 대신해 해소하지 않는 모호함인데, 작성자 대신 하나의 해석을 고르면 요청하지 않은 것을 배포할 수 있기 때문입니다. 또는 차단은 해당 표면 뒤의 동작이 출시될 때까지만 유지될 수도 있습니다. 어느 경우든 이 레이블이 약속하는 바는 같습니다. 스키마는 이를 받아들이고, 빌드는 이를 거부하며, 오류는 고치는 방법을 알려 줍니다. -
planned. 해당 표면은 설계된 대로 문서화되어 있지만 스키마와 컴파일러 모두 아직 이를 받아들이지 않습니다.
planned표면을 사용해 작성하면 스키마 검증에서 실패합니다. 이 페이지는 작성자가 빌드 시점에 공백을 발견하는 대신 그 부재를 감안해 계획할 수 있도록 계획된 항목을 드러냅니다.
상태 레이블은 현재 컴파일러를 기준으로 평가됩니다. 활발히 개발 중인 표면은 레이블 사이를 전환할 수 있으며, 전환 계획이 알려진 경우 섹션별 항목에서 이를 설명합니다.
Recipe 입력 종류
Recipe는 세 가지 입력 종류, 즉 소싱(sourced), 합성(synthesized), 아티팩트(artifacts)로부터 출력을 구성하며, 이는 16-recipe-input-composition.md에 설명되어 있습니다. 입력 종류별 상태:
-
source:+valuesMapping:(소싱) — available. 컴파일러는source:URI를 해석하고,valuesMapping템플릿(인라인, 파일$import:또는 라이브러리$import:)을 평가한 다음, 그 결과를 렌더링을 위해 대상 provider에 전달합니다. helm, helm-chart, compose, terraform, cloudformation provider가 사용합니다. -
workload:(합성) — available. Recipe는workload:를 인라인(Workload YAML을 담은 블록 스칼라)으로 선언하거나$import:(파일 경로)를 통해 선언합니다. 컴파일러는 템플릿 처리된 Workload를 파싱하고, 내장된 Workload 스키마에 대해 검증한 다음, 대상 provider의 workload 합성기로 디스패치합니다. helm 및 compose provider가 사용합니다. helm-chart provider는 합성된 K8s manifest에 대해 작성자를 helm provider로 명시적으로 안내합니다. workload 합성을 구현하지 않는 provider를 대상으로workload:를 선언하는 Recipe는 렌더링 시CATALOG_ERROR와 함께 중단됩니다. -
artifacts:(아티팩트) — available. 이 필드는 이름이 지정된 항목의 맵이며, 각 항목은 인라인으로 작성되거나 항목별$import:를 통해 로드됩니다. 항목은 Workload가 파싱되고 소스가 해석된 후에 평가되므로.workload와.source를 포함한 전체 템플릿 컨텍스트를 사용할 수 있습니다. 메타데이터를 가진 문서의 경우 출처 정보가metadata.labels와metadata.annotations에 병합되며(문자 집합상 안전하지 않은 키인 recipe-uri, boundary-path, sync-wave는 annotation으로 들어가며, 이는 helm provider가 적용하는 것과 같은 분할입니다), Recipe의 소스 렌더링 출력 또는 workload 합성 출력과 함께 별도 파일로 출력됩니다. Provider 디스패치: 플랫 helm provider는 boundary 출력 디렉터리 안에서 해당 항목을 선언한 component의 이름을 딴 디렉터리 아래에 독립 파일을 출력합니다. 키는 파일 이름만 정할 뿐 어느 component가 그 파일을 작성했는지는 알려 주지 않기 때문입니다. compose provider는 출력을 Release 종단 병합기를 통해 전달합니다. helm-chart provider는 모든 항목을[[ ]]Aggrega 구분자로 평가하여 같은 파일에 있는 Helm의{{ }}구문이 다운스트림 렌더링까지 유지되도록 한 다음, 각 항목을 작성된 형태에 따라 배치합니다.$import:로 로드된 항목은 소싱된 차트 자체의 템플릿과 함께boundaries/<bp>/charts/<nodeID>/templates/<authored-key>에 배치되고(번들의 파일은 해당 키 아래에 중첩됨), 인라인 콘텐츠 항목은 차트 루트인boundaries/<bp>/charts/<nodeID>/<authored-key>에 배치되며, 차트 자체의 템플릿은.Files.Get/.Files.Glob를 통해 이를 읽습니다. terraform provider는 각 항목을 boundary의modules/트리 아래에 있는 component 자체 디렉터리에 그대로 기록합니다. cloudformation provider는 스택 조각인 각 항목을 해당 출력 디렉터리용으로 조립되는 단일 스택에 병합합니다. 입력 종류 출처(소스 렌더링, workload 합성 또는 아티팩트 출력) 간의 파일 이름 충돌은 렌더링 시 교차 출처 충돌 탐지기에 의해 포착되며, 모든 기여자를 명시하는 CATALOG_ERROR를 발생시킵니다.
Recipe 작성 표면과 입력 종류 구성 규칙은 entities/recipe.md를, Recipe 형태 규칙은 errors/fatal-halts.md를, provider별 매트릭스는 아래의 Providers 섹션을 참조하십시오.
매핑 언어
Recipes(및 FeatureRecipes)는 Aggrega 컨텍스트를 기반 provider가 사용하는 values 딕셔너리로 변환하기 위해 단일 매핑 필드에 바인딩됩니다. valuesMapping: 필드는 콘텐츠 형태에 따라 디스패치되는 세 가지 작성 모드를 지원합니다.
valuesMapping:— 모드 1-3 사용 가능. 모드 1: 인라인 Go 템플릿(블록 스칼라). 모드 2: 파일$import:(로컬 파일 경로를 가진$import:만 포함하는 맵). 모드 3: 라이브러리$import:(MappingLibrary 항목에 대한 bare-name 식별 참조<Library>#/mappings/<entry>와 함께, 선택적으로:<version>하한을 지정하는$import:만 포함하는 맵). 컴파일러는 콘텐츠 형태에 따라 분기합니다. 블록 스칼라는 모드 1로, 파일 경로를 가진$import:는 모드 2로, bare-name 라이브러리 참조를 가진$import:는 모드 3으로 처리합니다. 세 모드 모두 값 매핑 중에 해석된 Go 템플릿을 Recipe의 템플릿 컨텍스트에 대해 평가합니다(Sprig 헬퍼 라이브러리가 미리 등록되어 있습니다). 모드 3은 로컬 카탈로그와 lockfile에 고정된 라이브러리를 대상으로 항목을 해석하며, 호스트를 포함한 참조는 거부됩니다. 분기 메커니즘과 예제는entities/recipe.md의 “ThevaluesMappingfield — three authoring modes”를 참조하십시오.
Recipe 작성 인터페이스와 매핑 언어 설계는 entities/recipe.md를, 모드 3을 뒷받침하는 라이브러리 엔터티는 entities/mappinglibrary.md를 참조하십시오.
Inject 구문
inject: 블록은 모든 위치에서 하나의 구문을 사용합니다. 컴포넌트 자체의 inject, uses 연결의 inject, 연결된 attachment의 inject 모두 같습니다.
-
메커니즘별 항목 목록(
[{in: ..., from: ...}],[{in: ..., value: ...}]) — 사용 가능. 각 전달 메커니즘은 목록입니다. 각 항목은in:으로 로컬 식별자(환경 변수 이름, 파일 경로, 인수 플래그)를 지정하고,from:(provides 키 참조) 또는value:(리터럴 문자열) 중 정확히 하나를 가집니다. 목록이 아닌 맵으로 작성된 메커니즘이나 두 키워드를 모두 가진 항목은 Aggregate의 문서 엔벌로프에서 빌드를 중단시키며, 해당 경로를 알려 줍니다. -
value:는 컴포넌트 자체의inject에서만 사용합니다. 리터럴은 컴포넌트 자체의inject에 속하며, 그것이 리터럴을 전달합니다.uses연결에서는 Aninject:entry on a connection carries a literal(연결의 항목이 리터럴을 포함함)에서 설명하듯이value:가 빌드를 중단시키고, attachment 자체의inject에서도 Aninject:entry on an attached Feature carries a literal(첨부된 Feature의 항목이 리터럴을 포함함)에서 설명하듯이 빌드를 중단시킵니다. 둘 다 다른 엔터티가 게시하고from:으로 지정한 키만 전달합니다.
이중 상태 컨텍스트 의미, 키 충돌 규칙, 작업 예제를 포함한 전체 Injection Contract 명세는 vocabulary/topology-triad.md를 참조하십시오.
템플릿 엔진
Aggrega의 Go 템플릿 엔진은 Recipe 및 FeatureRecipe 템플릿을 템플릿 확장 매트릭스가 문서화하는 사이트별 단계에서 템플릿 컨텍스트에 대해 평가합니다. Sprig 헬퍼 라이브러리는 렌더러가 평가하는 모든 표면에서 Aggrega 자체 헬퍼와 함께 사전 등록되며, 예외가 하나 있습니다. 구조화된 source: 좌표를 해석할 때는 Aggrega의 헬퍼만 등록됩니다. 그곳에서는 optional과 capitalizedWords를 사용할 수 있지만 Sprig의 함수는 사용할 수 없으므로, source: 필드 또는 구조화된 source:를 가진 엔터티의 locals: 항목에서 Sprig를 호출하면 파싱 시점에 중단됩니다. 해당 표면을 별도 섹션으로 다루는 errors/fatal-halts.md를 참조하십시오. 평가, 파싱, Sprig 통합은 현재 사용할 수 있습니다.
누락된 키 동작 — 값 템플릿에서는 허용되며, 경로 템플릿, 어서션, source: 좌표에서는 엄격한 missingkey=error가 적용됩니다. 값 템플릿은 Go의 missingkey=zero 옵션으로 평가되므로, 바인딩되지 않은 키(예: .values.unset_field)를 참조하는 템플릿은 오류를 발생시키지 않으며 해당 읽기는 아무것도 렌더링하지 않습니다. {{ .values.optional_field | default "fallback" }} 같은 카탈로그 관용구는 이 정책에서도 계속 동작하는데, 설정되지 않은 값은 default에서 빈 값으로 간주되기 때문입니다. 경로 템플릿(Release 경계의 directory: / subDirectory:)은 닫힌 허용 목록에 대해 missingkey=error로 평가됩니다. 조용한 경로 실패는 운영자가 빌드 후에야 발견하는 깨진 파일 시스템 레이아웃을 만들어 내며, 엄격한 정책은 오류를 더 일찍 잡아냅니다. 다른 두 표면도 같은 이유로 동일한 엄격한 정책을 따릅니다. 그곳에서 빈 렌더링은 작성자가 다시 읽어 볼 수 있는 필드가 아니라 잘못된 판정이나 잘못된 고정 값을 만들어 내기 때문입니다. 이 두 표면은 Component, Feature, Recipe 또는 FeatureRecipe의 assertions: 항목과, Recipe 또는 FeatureRecipe에 있는 구조화된 source: 블록의 템플릿 필드입니다. errors/fatal-halts.md는 각 표면의 정책을 하나씩 설명하고 엄격한 정책에서 동작하는 존재 인식 형식을 제공합니다.
optional을 통한 존재 인식 대체 값. Recipe 작성자가 “키 없음”과 “0 / 빈 값 / false 값을 가진 키 있음”을 구별해야 할 때(Sprig의 default로는 할 수 없는 구별), 렌더러는 optional 헬퍼를 제공합니다. {{ optional .infra "replicas" 1 }}는 작성된 infra.replicas가 있으면(작성된 0 포함) 그 값을 반환하고, 키가 없을 때만 1로 대체합니다. 전체 의미는 templates/sprig-functions.md를 참조하십시오.
capitalizedWords를 통한 이름 변환. 대상이 리소스를 가리키는 이름에 문자와 숫자만 허용하는 경우, {{ capitalizedWords .context.instance_id }}는 id를 해당 문자 집합 밖의 문자로 구분된 단어들로 읽고 각 단어의 첫 글자를 대문자로 바꾸므로, payments-db는 PaymentsDb가 됩니다. 이 변환은 모든 구분자를 제거하므로 구두점만 다른 두 id는 같은 이름이 됩니다. 하나의 이름으로 두 리소스를 내보내게 되는 빌드는 중단되며 두 id를 모두 보고합니다. 전체 의미는 templates/sprig-functions.md를 참조하십시오.
선언 계층에서의 매개변수 계약 적용. Release가 제공하지 않는 필수 매개변수는 해석이 가장 먼저 검사하는 매개변수 계약 계층에서 명시적 오류를 발생시키며, 매개변수와 계약을 지목하는 file:line 출처 정보가 함께 제공됩니다. 타입 / 제약 조건 위반도 같은 방식으로 드러납니다. 이것이 실질적인 누락 키 검사입니다. 타입은 하위 단계의 템플릿 평가 시점이 아니라 개발자의 의도가 있는 곳(Aggregate의 parameters: 선언)에서 검사됩니다. entities/aggregate.md §“Typed parameter contracts”를 참조하십시오.
Aggregate parameters:의 단일 선언 문법. 각 매개변수 슬롯은 타입 계약 객체(key: { type: <type>, default: <value>, ... })로 작성합니다. 단순 스칼라 축약형(key: <value>)은 Aggregate의 문서 엔벌로프에서 거부되며, 해당 매개변수를 지정하고 객체가 필요하다고 알려 주는 오류가 표시됩니다. 타입 계약 어휘는 선언 계층에서 type:, required: 및 제약 조건 의미를 명시적으로 만듭니다. Release의 값 충족은 계약에 선언된 타입에 따라 계속 스칼라 값을 사용합니다.
템플릿 사이트별 평가 매트릭스는 templates/expansion-matrix.md를, 템플릿 개요는 05-templates.md를 참조하십시오.
컴파일 파이프라인 단계
Aggrega 컴파일 파이프라인은 ../architecture/10-compilation-pipeline.md에 문서화되어 있습니다. 단계별 상태는 다음과 같습니다.
- 해석, 토폴로지 구성, 그래프 확정, 정적 분석 및 렌더링 — 사용 가능.
- inject 매핑(
injectMapping렌더링 전 가로채기)과 모든 기본 렌더링 하위 단계 — locals 게시, values 매핑, workload 합성, artifact 평가, provider 렌더링, feature 렌더링, 자격 증명 FeatureRecipe 리소스 생성 — 사용 가능. - 플러그인 파이프라인(
pipeline:Wasm 실행) — 사용 가능. 비어 있지 않은pipeline:단계를 선언한 Recipe 또는 FeatureRecipe는 각 단계가 선언된 순서대로 실행됩니다. 컴파일러는 렌더링된 출력을 대상으로 단계에 지정된 Wasm 플러그인을 호출하고, 반환된 JSON Patch 연산을 대상 문서에 적용하며, 단계의 부수 효과를 내보냅니다.when:조건이 거짓으로 렌더링되는 단계는 통과(pass-through)로 건너뛰며 문서 집합은 변경되지 않습니다. JSONPatch 방식의 변경(Envoy 사이드카 주입, secret VolumeMount 등)을 목표로 하는 작성자는 이 기능을 통해 이를 구현합니다.
Providers
Aggrega 표준 라이브러리는 다섯 가지 렌더링 provider인 helm, helm-chart, compose, terraform, cloudformation을 제공합니다. provider별 상태는 다음과 같습니다.
helm— 사용 가능. 소스 모드(Helm SDK를 통한 Helm 차트 렌더링)와 합성 모드(Workload → Workload의form에 따라 선택되는 컨트롤러 객체인 Deployment, StatefulSet, DaemonSet, Job 또는 CronJob과 Service 및 PVC)가 모두 제공됩니다.helm-chart— 사용 가능. 소스 모드(엄브렐라 차트 구성)가 제공됩니다. 합성 입력 종류는 이 provider에 적용되지 않습니다. K8s 매니페스트 합성이 필요한 작성자는workload:와 함께helmprovider를 사용합니다.compose— 사용 가능. 소스 모드(compose 프래그먼트 오버레이)와 합성 모드(Workload → compose 서비스 + 볼륨 + 네트워크)가 모두 제공됩니다. 경계별docker-compose.yaml출력은 Release 수준 컴포저를 통해 조립됩니다.terraform— 사용 가능. 소스 모드와 아티팩트가 모두 제공됩니다. 각 경계는 하나의 루트 구성aggrega.modules.tf를 가지며, 이 구성은 모든 컴포넌트를module블록으로 선언하고 해당 파일은modules/아래 컴포넌트 자체 디렉터리에 위치합니다. 합성 입력 종류는 이 provider에 적용되지 않습니다.cloudformation— 사용 가능. 소스 모드와 아티팩트(스택 조각)가 모두 제공됩니다. 하나의 출력 디렉터리로 렌더링되는 모든 컴포넌트는 하나의 스택 템플릿으로 조립되어 순수 JSON으로 출력됩니다. 합성 입력 종류는 이 provider에 적용되지 않습니다.
Provider 렌더링은 pluginType: provider를 가진 Plugin이 담당합니다. 프로바이더 렌더링 Plugin 작성 방법은 entities/plugin.md를, 프로바이더별 레퍼런스 페이지는 06-providers.md를 참조하십시오.
어노테이션 기반 확장
Manifests는 어노테이션 키를 Feature 타입에 매핑하는 features.annotations: 바인딩 섹션과, 각 바인딩이 채울 수 있는 Feature 스키마 속성을 지정하는 필러별로 그룹화된 라우팅 테이블(maps.infra / maps.values)을 포함합니다. entities/manifest.md와 providers/well-known-annotations.md에 문서화되어 있으며, 파이프라인 내 위치는 ../architecture/10-compilation-pipeline.md에, 카탈로그 로드 시점과 inspect 시점의 동작 방식은 ../architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion”에 설명되어 있습니다.
- Manifest
features.annotations바인딩 — 사용 가능. 해석 단계의 어노테이션 확장 하위 단계가 엔드 투 엔드로 제공됩니다. 이 단계는 Release 경계(바깥에서 안쪽으로)와 Aggregate 하위 시스템(바깥에서 안쪽으로)을 순회하고, 값 전체 및 하위 키별 null 옵트아웃을 포함한 캐스케이드 + 오버라이드를 통해 컴포넌트별 유효 어노테이션 집합을 계산하며, 각 어노테이션 값을 스칼라, 구조화된 맵 또는 명시적null로 파싱하고, 사이드 대 필러 강제(Aggregate 측은maps.values를, Release 측은maps.infra를 발동)와 함께 바인딩의maps선언을 통해 하위 키별로 라우팅하며, 대상 Feature의spec.schema에 대해 리프별 타입을 검증하고, 합성 Feature 첨부를 주입합니다. IR 그래프는 이 첨부를origin: annotation으로 표시합니다. 사이드 간 구성은 IR 빌드 시점에 필러별·필드별로 병합되며 필드마다 명시적 값이 우선합니다.aggrega inspect는 리프마다 출처 정보 괄호를 렌더링합니다. 카탈로그 로드 시점의 바인딩 대상 검증, 스키마-필러 중복 린트, 바인딩-맵 중복 린트가 이 경로를 통제합니다. 접두사aggrega.ai/단독을 바인딩 키로 사용하면 Manifest 로드 시 거부됩니다. 이 접두사는 플랫폼 고유 어노테이션용으로 예약되어 있으며, 바인딩은feature.aggrega.ai/또는 사용자 정의 도메인을 사용합니다.
버전 매칭
Recipes와 FeatureRecipes는 implements: 키워드를 통해 자신이 구현하는 Component 또는 Feature 인터페이스를 선언합니다. implements:는 Recipe를 선택하지 않습니다. 선택은 Manifest의 매핑이 하며, 어떤 매핑도 해당 타입을 다루지 않는 인스턴스는 그 타입을 구현할 수 있는 implements:를 가진 Recipes를 후보로 나열하는 오류와 함께 중단됩니다. implements:가 주도하는 것은 각 Manifest 매핑 항목의 Recipe가 매핑된 타입 또는 그 타입이 extends하는 기반을 구현하는지에 대한 검사입니다. 매핑된 타입은 항목의 키이며, components.type 키의 경우 키가 지정하지 않은 버전으로 키가 도달하는 각 컴포넌트 인스턴스의 타입이기도 합니다(버전 없이 작성된 키라면 도달하는 모든 인스턴스). 이때 버전은 빌드가 해당 인스턴스를 컴파일하는 버전, 즉 인스턴스가 지정한 버전이거나, 버전을 지정하지 않은 인스턴스의 경우 카탈로그가 보유한 해당 Component의 최고 버전입니다. 형식별 상태:
- 정확한 형식(
core/api-server:1.0.0) — 사용 가능. 매핑된 타입은 해당 버전이어야 합니다. - 메이저 호환 범위(
core/api-server:^1.0.0) — 사용 가능. 캐럿 형식은 SemVer 제약 조건(이 예에서는>=1.0.0, <2.0.0)이며, 매핑된 타입의 버전이 이를 충족해야 합니다. - 버전 없음(
core/api-server) — 사용 가능. 해당 타입의 모든 버전이 이를 충족합니다.
Recipe의 implements:가 매핑된 타입과도, 그 기반 중 어느 것과도 일치하지 않는 매핑 항목은 해당 항목, Recipe, 그리고 그 implements: 값을 지정하는 OPS_ERROR로 빌드를 중단시킵니다. 키가 다른 버전으로 도달하는 컴포넌트 인스턴스의 버전을 Recipe의 implements:가 충족하지 않으면, 빌드는 같은 OPS_ERROR로 중단되며 해당 인스턴스, 그 타입(버전을 지정하지 않은 인스턴스의 경우 컴파일된 버전도 포함), 키, Recipe, 그리고 그 implements: 값을 알려 줍니다. 캐럿 형식은 메이저 호환 매칭을 위한 표준 작성 방식입니다.
implements: 설계 방식은 vocabulary/inheritance-and-interface.md를, Manifest별 매핑 계층 구조는 entities/manifest.md를 참조하십시오.
메타데이터 엔벌로프
카탈로그 엔티티 엔벌로프에는 metadata.labels, metadata.annotations, 그리고 (Release에서는) metadata.environment가 포함됩니다. 표면별 상태는 다음과 같습니다.
metadata.labels 및 metadata.annotations 사용 가능 여부 — 일곱 가지 종류에서 사용 가능. 이 필드를 포함하는 엔티티 엔벌로프는 Component(labels 필수이며 필수 키 component.aggrega.ai/type를 포함, annotations는 선택), Feature(둘 다 선택), 네 가지 라이브러리 종류인 SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary(둘 다 선택), 그리고 Aggregate(labels만, 선택)입니다. 나머지 엔티티인 Recipe, FeatureRecipe, Manifest, Release, Plugin은 엔벌로프 수준에서 metadata.labels 또는 metadata.annotations를 허용하지 않습니다.
Release의 metadata.environment — 필수. Release 스키마는 environment를 필수 metadata 필드로 나열하며, 빌드는 그 값을 렌더링된 출력에 aggrega.ai/environment 레이블로 기록합니다. Environment Metadata 섹션의 다섯 가지 실용적인 사용 사례(OTel/FinOps 비용 귀속, OTel 트레이스/로그 필터링, Kubernetes 오퍼레이터 대상 지정, 다중 리전 프로덕션 구분, 컴플라이언스 범위 지정)는 entities/release.md를 참조하십시오.
metadata 키에 적용되는 필드 대소문자 원칙은 02-naming-conventions.md를, 각 엔티티가 현재 허용하는 엔벌로프 형태는 엔티티별 참조 페이지를 참조하십시오.
CLI 명령
Aggrega CLI는 빌드 파이프라인과 인트로스펙션을 등록합니다. 명령별 상태:
aggrega build— 사용 가능. Release 파일을 읽고, Aggregate + Manifest를 해석하고, 컴파일 파이프라인을 실행하고, 렌더링된 아티팩트를 경계 출력 디렉터리에 씁니다. lockfile이 있으면 그에 대해 의존성을 검증하고, 없으면 pull을 요청하며 중단하거나,--auto-pull또는auto_pull이 요청하는 경우 먼저 lockfile을 채웁니다.aggrega inspect— 사용 가능. 카탈로그 엔터티, 엔터티 파일, 레지스트리에 게시된 엔터티 또는 Release를 검사하고 해석된 형태를 보고합니다.cli/aggrega-inspect.md를 참조하십시오.aggrega pull— 사용 가능. Release의 모든 의존성을 해석하고, 모든 카탈로그 엔터티와 소스 아티팩트를 버전과 콘텐츠 다이제스트에, Release의 렌더링이 요청하는 모든 외부 입력을 콘텐츠 다이제스트에 고정하는 Release별 lockfile을 씁니다. 가져온 콘텐츠는.aggrega/cache아래에 캐시합니다.--verify는 기존 lockfile을 현재 상태와 대조하여 확인합니다.cli/aggrega-pull.md를 참조하십시오.aggrega push— 사용 가능. 카탈로그 엔터티를 OCI 레지스트리에 게시합니다.aggrega push --list-kinds는 허용하는 종류를 보고합니다.cli/aggrega-push.md를 참조하십시오.aggrega lint— 사용 가능. 카탈로그 전체, Release의 의존성 클로저 또는 하나의 엔터티에 대해 게시 규율 규칙을warn심각도로 실행합니다. 하나의 엔터티에 대해서는--pre-publish가 엔터티의 현재 게시된 버전에 대한 버전 증가 검사를 추가하며, 불일치하면 중단됩니다. 이 규칙은 옵트인 Wasm 플러그인으로 제공됩니다.cli/aggrega-lint.md를 참조하십시오.aggrega serve— 사용 가능. 편집기 및 IDE 통합을 위해 stdin/stdout을 통해 JSON-RPC 2.0으로 통신하는 장기 실행 서비스형 컴파일러 데몬입니다. 제공하는 메서드는cli/aggrega-serve.md를 참조하십시오.aggrega version— 사용 가능. CLI 버전을 출력합니다.-o json은 기계가 읽을 수 있는 버전 객체를 내보냅니다.aggrega validate— 사용 가능. 전체 카탈로그, Release 또는 단일 엔터티에 걸쳐 정확성을 검사하며, 아티팩트를 렌더링하지 않고 진단을 보고합니다.aggrega search— 사용 가능. 구성된 레지스트리의 로컬 인덱스에서 게시된 엔터티를 검색합니다. 인덱스는aggrega registry update가 빌드하고 갱신합니다.aggrega registry— 사용 가능. 레지스트리와 그 서명 신뢰 정책을 관리합니다.registry add는 레지스트리를 기록하고,registry update는aggrega search가 조회하는 로컬 인덱스를 빌드합니다.aggrega push-artifact— 사용 가능. 엔터티를 게시하는push와 함께, 독립형 데이터 아티팩트(예: 문서 번들)를 OCI 레지스트리에 게시합니다.aggrega sign— 사용 가능. 이미 게시된 하나 이상의 아티팩트에 서명하고 그 서명을 첨부합니다.aggrega deprecate— 사용 가능. 이미 게시된 아티팩트에 서명된 지원 중단 표시를 첨부합니다.aggrega login및aggrega logout— 사용 가능. OCI 레지스트리에 인증하고 자격 증명을 저장하거나, 저장된 자격 증명을 제거합니다.aggrega auth— 사용 가능. 아티팩트 서명에 사용하는 로컬 서명 ID를 관리합니다.aggrega config— 사용 가능. 워크스페이스 구성을 검사하고 관리합니다. 하위 명령은 병합된 유효 구성과 각 설정의 출처를 표시하고, 레지스트리와 그 서명 신뢰 정책으로 작업 구성을 초기화하며, 유효한 빌드 핵심 구성을 워크스페이스에 고정하여 머신의 전역 구성에 의존하지 않고 동일하게 빌드되도록 합니다.aggrega get-schema— 사용 가능. 엔터티 또는 계약 종류의 JSON Schema를 출력합니다.aggrega plugin— 사용 가능. CLI가 해석할 수 있는 Wasm 플러그인을 검사합니다. 하위 명령은 플러그인을 나열하고, 구성된 플러그인을 추가 및 제거하고, 플러그인의 기계 소유 레코드를 동기화하고, 플러그인의 카탈로그 뷰를 생성합니다.aggrega cache— 사용 가능. 디스크 캐시를 검사하고 유지 관리합니다. 하위 명령은 상태 보고, 정리(prune), 축출(evict), 삭제(clear)를 수행합니다.aggrega mcp— 사용 가능. stdio를 통해, 또는 다른 머신의 클라이언트를 위해 HTTPS를 통해 Model Context Protocol 서버를 실행하여 컴파일러의 인트로스펙션을 AI 어시스턴트 통합에 노출합니다.aggrega completion— 사용 가능. CLI용 셸 자동 완성 스크립트를 생성합니다.- CLI 확장 하위 명령 — 사용 가능.
pluginType: cli게스트로 게시된 Wasm 플러그인은 해석되어aggrega하위 명령으로 등록되므로, 설치된 확장은 기본 제공 명령과 함께aggrega <extension>으로 실행됩니다. aggrega import— 사용 가능. 외부의 선언적 에이전트 정의 소스(Langflow, Flowise, n8n)를 Aggregate 및 Component 작성 파일 초안으로 변환하며, 노드별로 결정적인 신뢰도 점수 기반 카탈로그 재사용 결정을 기록합니다. 형식별 매핑은 워크스페이스가 소스 형식에 대해 해석하는 임포터 플러그인이 제공합니다. 이는 카탈로그가 보유한 것이거나, 각 컴파일러 릴리스와 함께 빌드되어 게시되는 컴파일러의 Langflow, Flowise 및 n8n 임포터 중 하나입니다. 바이너리는 이들의 Plugin 엔터티를 포함하지만 모듈은 포함하지 않으므로, 이들은 모든 워크스페이스에서 해당 형식을 처리합니다. 머신에 없는 임포터가 필요한 첫 번째 가져오기는 워크스페이스의 기본 레지스트리에서 이를 가져와 검증하고, 이후의 모든 가져오기를 위해 콘텐츠 캐시에 보관합니다. 소스는 워크스페이스의 카탈로그가 해당 구문에 대해 제공하는 파서로 구문 분석되며, 카탈로그가 제공하지 않는 경우 컴파일러가 포함한 파서로 구문 분석되므로, 카탈로그에 파서가 없는 워크스페이스도 어느 쪽으로든 가져올 수 있습니다.aggrega scaffold— 사용 가능. 모든 엔티티 종류에 대해 해당 종류의 스키마로부터 시작 문서 초안(필요한 모든 필드를 포함하고 값이 필요한 곳에는 자리 표시자를 넣은 문서)을 만들어 표준 출력에 씁니다.--example을 지정하면 서명된 문서 번들에서 읽은, 문서의 실행 가능한 예제 중 하나를 새 디렉터리에 씁니다.aggrega explain— 사용 가능. 짧은 코드(예:E0007) 또는 설명형 코드가 가리키는 중단 조건을 설명합니다.aggrega edit-document— 사용 가능. 문서에 범위가 제한된 구조적 편집 하나(컴포넌트 추가, Feature 연결, 연결 배선, 값 하나 설정)를 적용하며, 건드리지 않는 모든 바이트를 보존합니다.aggrega pin— 사용 가능. Recipe 또는 FeatureRecipe 옆의entity.lock에, 엔티티가 자신의 문서 밖에서 읽는 모든 입력에 대한 콘텐츠 고정값을 기록합니다.aggrega skills— 사용 가능. AI 어시스턴트에 Aggrega 스킬을 설치합니다.
CLI 개요는 07-cli.md를, 명령별 참조 페이지는 언어 레퍼런스 색인을 참조하십시오.
편집기 및 기타 프런트엔드
모든 프런트엔드는 aggrega 바이너리가 컴파일한 결과를 보여 주며, 자체 컴파일러를 가진 프런트엔드는 없습니다. 표면별 상태:
- IR 그래프 계약 — 사용 가능. 모든 프런트엔드가 그래프를 읽을 때 기준으로 삼는 계약인 IR 그래프 스키마는 Aggrega 스키마 배포판의 일부로 제공됩니다. IR 스키마 참조를 참조하십시오.
- 명령에서 그래프 읽기 — 사용 가능.
aggrega build는--ir-graph를 받으며, Release가 주어진aggrega inspect와aggrega validate --release도 마찬가지입니다. 이 플래그는 명령이 원래 생성하는 출력에 더해 해당 실행에서 해석된 그래프를 JSON으로 stdout에 기록합니다. 데몬 세션은aggrega/irGraph에서 같은 그래프를 읽으며, MCP 서버의cli-inspect,cli-build,cli-validate도구는 이를ir_graph인수로 받습니다. - Visual Studio Code의 토폴로지 그래프 — 사용 가능. Visual Studio Code용 Aggrega 확장은 선택한 Release의 IR 그래프를 대화형 그래프로 그리고 그 그래프에서 Features를 첨부하며, 두 작업 모두
aggrega serve데몬에 요청합니다. - 헤드리스 CLI 스트리밍 모드 — 계획됨. 헤드리스 모드는 토폴로지가 변경될 때 프런트엔드가 사용할 수 있도록 IR 그래프를 줄 단위로 구분된 JSON으로 stdout에 출력합니다. 현재 제공되는 것은 스트림이 아니라 호출당 하나의 문서입니다. 토폴로지가 변경될 때 하나의 stdout에 일련의 그래프를 출력하는 명령은 없습니다.
편집기, 어시스턴트, 데몬이 컴파일러에 접근하는 방법은 ../architecture/15-editors-assistants-and-frontends.md를 참조하십시오.
설계 방향
위의 상태 분류는 언어 전반에 걸쳐 표면별 상태를 분류하며, 이 섹션은 아키텍처 장에 문서화된 더 넓은 설계 방향의 상태를 기록합니다.
전사적 컴플라이언스는 계획된 방향이 아닙니다. 거버넌스 규칙을 한 번 명시하여 워크스페이스의 모든 빌드에 적용하는 기능은 현재 거버넌스 소켓을 통해 사용 가능합니다. 워크스페이스 구성의 plugins.governance 키에 연결된 플러그인은 해당 워크스페이스의 모든 빌드를 평가합니다. 판정 역할은 규칙을 위반하는 그래프나 렌더링된 아티팩트를 거부하고, 변환 역할은 개발자가 직접 입력하지 않는 파생 메타데이터를 제공합니다. ../architecture/11-governance-and-compliance.md를 참조하십시오.
- 인터페이스 동등성 및 자동 구현 — 사용 가능. 기본 Component를 대상으로 작성된 Recipe는 체인의 깊이와 관계없이 그것을 확장하는 모든 Component에 사용되므로, 아키텍트가 중복 Recipe를 작성할 필요가 없습니다. 확장하는 Component는
schema: inherited를 작성하므로, 기본 Recipe가 소비할 수 없는 루트 키를values/infra/provides에 추가하지 않습니다. 자체 스키마를 가진 채extends를 선언하는 Component는 문서 엔벌로프에서 거부됩니다. Manifest는 여전히 확장 타입을 자체 항목으로 매핑하며, 매핑된 Recipe의implements가 그 타입 또는 그 타입이 확장하는 기반 중 하나를 지정하면 매핑 검사가 이를 허용합니다.../architecture/02-ecosystem-philosophy.md에 문서화되어 있습니다. - Ghost Infrastructure Tracker — 사용 가능. 렌더링 단계 가드레일로, 작성자가 선언한 키가 노드에 도달했지만 바인딩된 Recipe가 선언한 어떤 템플릿도 그 키를 읽지 않으면 경고를 내보냅니다. 따라서 작성자가 선언하고 템플릿이 조용히 누락한 값은 사라지는 대신 명시됩니다. 이는 동일한 형태 일치 설계의 렌더링 단계 측면입니다.
errors/warnings.md를 참조하십시오.
아키텍처 장은 설계 표면을 설명하고, 이 페이지는 구현 상태를 추적합니다.