아키텍처 불변 조건
이 여덟 가지 불변 조건은 Aggrega의 기본 원칙입니다. 이 조건들은 여러 릴리스에 걸쳐, 그리고 컴파일러 코어, 스키마 계층, 카탈로그, Wasm 플러그인 표면 전반에 걸쳐 유지됩니다. 모든 설계 결정, 모든 기능, 그리고 작성된 모든 엔터티는 이 조건들을 따릅니다.
다른 아키텍처 장에서는 불변 조건을 번호로 참조합니다. 이후의 장에서 “불변 조건 2에 따라” 또는 “String Pipe 규칙(불변 조건 3)에 따라”라고 하면 여기를 가리킵니다.
1. 컴파일러는 내용에 중립적이고, 주관이 없으며, 사용자 의도에 구애받지 않는다
Aggrega 컴파일러는 사전(Ahead-Of-Time, AOT) 텍스트 라우터입니다. YAML을 파싱하고, 그래프를 순회하고, 레이블 교집합을 평가하며, 문자열을 소스에서 싱크로 전달합니다. 작성자가 values, parameters, infra, provides, locals에 무엇을 넣는지 단속하지 않습니다. 명명 관례, 포트 관례, 또는 Architect가 만들어 내는 의미 레이블을 강제하지 않습니다.
컴파일러 규칙처럼 들리는 많은 규칙 — Zero-Port Contract, Naked-Base / Flavored-Edges 카탈로그 스타일, 특정 컴포넌트에 어떤 운영 프리미티브가 맞는지에 대한 선택 — 은 사회 계약(Social Contracts)입니다. 즉, 탈출구가 있는 모범 사례이며, 표준 라이브러리 카탈로그를 작성하는 Platform Architect들이 지켜 나갑니다. 컴파일러는 이를 해석하지 않습니다.
이 불변 조건은 작성한 콘텐츠에서 컴파일러가 무엇을 추론하는지에 관한 것이며, 그 범위가 전부입니다. 몇몇 키는 Aggrega 자체 키입니다. 이 키들은 예약되어 있고, 허용하는 값이 게시된 스키마에 기록되어 있으며, 스키마는 다른 선언된 필드와 같은 방식으로 이를 검사합니다. component.aggrega.ai/type이 그중 하나입니다. 그 값 집합은 닫혀 있으며, 집합 밖의 값을 가진 문서는 로드될 때 거부됩니다. 이것은 플랫폼이 자신의 키가 무엇을 뜻하는지 밝히는 것이지, 작성한 문자열에서 컴파일러가 의미를 읽어 내는 것이 아니며, 사용자 자신의 모든 키는 이 불변 조건이 말하는 그대로 단속되지 않은 채로 남습니다. Aggrega 정의에 없는 축으로 컴포넌트를 분류하는 카탈로그는 자체 레이블 키를 작성하며, 스키마는 이를 임의의 문자열 값으로 받아들이고 모든 셀렉터 표면은 이를 동일하게 읽습니다.
컴파일러가 실제로 강제하는 것은 좁습니다. 스키마 검증, YAML 파싱, 그래프 구성, 템플릿 평가, 그리고 Injection Contract의 단순한 텍스트 라우팅입니다. 그 밖의 모든 것은 관례이며, 카탈로그 작성 시점이나 선택적으로 사용하는 Wasm 거버넌스 소켓 안에서 강제됩니다.
자체 내부 카탈로그를 작성하는 기업은 표준 라이브러리 관례를 깨뜨릴 자유가 명시적으로 있습니다. 컴파일러는 스키마 검증을 통과하기만 하면 그들이 작성한 무엇이든 받아들입니다. 아키텍처는 모범 사례를 장려할 뿐, 감옥을 짓지 않습니다.
2. AOT 순수성: 컴파일러는 런타임 정보에 접근할 수 없다
Aggrega 자체는 Ahead-Of-Time 컴파일러입니다. 컴파일 시점에는 다음과 같습니다.
- 클라우드 API에 인증하지 않습니다.
- 실시간 IP 주소, DNS 이름, 클라우드가 생성한 URL을 가져오지 않습니다.
- 시크릿을 평문으로 해석하지 않습니다. 시크릿은 중간 표현(Intermediate Representation) 전체에서 메타데이터 포인터로 남습니다.
- 대상 클러스터나 서비스의 런타임 상태를 알지 못합니다.
- 아직 존재하지 않는 데이터(프로비저닝 이후의 엔드포인트, 동적으로 할당되는 포트, 자동 생성되는 리소스 이름)를 가져올 수 없습니다.
런타임 상태에 의존하는 모든 것은 결정적 포인터 문자열 — 안정적인 DNS 이름, Terraform 보간 문자열, CloudFormation 리소스 참조 — 로 표현되며, 이는 Ops Recipe 쪽에서 제공합니다. 컴파일러는 포인터를 해석하지 않고 그대로 전달합니다. 최종 물리 데이터는 런타임 환경(클러스터, IaC 상태 관리자)이 해석합니다.
이것이 진정한 제어 역전(True Control Inversion)입니다. 개발자는 Aggregate 안에서 Injection Contract를 지정하고, 컴파일러는 결정적 포인터를 미리 연결하며, 런타임 환경은 최종 물리 데이터를 해석합니다. 실제로 런타임 해석이 필요한 요구 사항은 컴파일러 코어가 아니라 Ops Recipe 안의 Wasm 파이프라인에 속합니다.
3. String Pipe: 컴파일러는 의미를 추론할 수 없다
컴파일러는 전달되는 값이 무엇을 의미하는지 해석하지 않습니다. Component A가 Component B를 사용할 때, 컴파일러는 Component B의 Recipe가 provides를 통해 생성하는 스칼라 — 문자열, 숫자 또는 불리언 — 를 가져와 Component A의 Recipe 컨텍스트로 전달하며, 이 값은 주입 경계에서 결정적으로 문자열화됩니다. 그 값이 FQDN이든, 로컬 호스트 이름이든, IP 리터럴이든, 포트 번호이든, Wasm 형식의 DSN이든 아무런 차이가 없습니다. 컴파일러는 라우팅 가능성, 프로토콜의 정확성, 의미상의 적절성을 검증하지 않습니다.
여기서 두 가지 결과가 따릅니다.
- 컴파일러는 이름으로 컴포넌트의 목적을 추측하지 않습니다.
database-production이라는 이름의 컴포넌트는 데이터베이스로 인식되지 않습니다.component.aggrega.ai/type같은 의미 유형 레이블(있는 경우)은 레이블 매칭에 사용되는 불투명한 메타데이터이지, 컴파일러의 분기 로직이 아닙니다. - 컴파일러는 호스트 이름, 데이터베이스 이름, 포트 번호, 임의의 불투명한 값을 서로 구별하지 않습니다. 이들은 모두 주입 컨텍스트의 스칼라 항목이며 문자열로 전달됩니다.
토폴로지 삼요소 — 생성하는 Recipe 쪽의 provides, 소비하는 Aggregate 쪽의 uses, 엣지의 inject — 가 Injection Contract입니다. 컴파일러는 레이블을 평가하고 문자열을 전달하며, 해석은 Recipe 항목과 Component 항목 사이의 작성 계약입니다.
4. 유령 인프라 금지: 컴파일러는 컴퓨팅이나 기능을 절대 만들어 내지 않는다
컴파일러는 컴퓨팅, Features, 어노테이션, 라우팅 프록시, 또는 작성자가 명시적으로 선언하지 않은 그 밖의 어떤 리소스도 몰래 주입하지 않습니다. 정책 위반은 요란한 가드레일(Loud Guardrails)을 만듭니다. 즉 빌드가 중단되고, 작성자가 쓴 문서에서 무엇을 고쳐야 하는지 알려 주는 구체적인 오류가 표시됩니다. 디버깅 시점에 인프라 수수께끼를 낳는 조용한 변경이 아닙니다.
리소스는 작성 시점의 명시적 선언을 통해 그래프에 들어옵니다.
- 개발자의 Aggregate 항목(컴포넌트,
uses엣지, Feature 연결). - Release 쪽 Feature 연결(운영자 수준의 추가).
- 어노테이션 기반 확장(Manifest 항목이 어노테이션 → Feature 바인딩을 선언하며, Component 항목이나 경계에 붙은 어노테이션은 명시적 선언입니다).
- Recipe 수준의 리소스 생성: Recipe 쪽
source렌더링이 기본 아티팩트를 생성하고,workload합성이 프로바이더별 배포 형태(Pod 스펙, Compose 서비스 등)를 내보내며,artifacts:항목(인라인 또는$import:로 로드한 것)이 Recipe 고유의 보조 매니페스트를 내보내고, FeatureRecipe 리소스 생성이 명시적인 Feature 연결을 계기로 Feature 단위의 보조 리소스를 내보냅니다.
Recipe 수준의 경로는 한 단계 떨어진 작성 시점 선언입니다. Recipe 작성자는 Component 계약에 맞추어 source / workload / artifacts / valuesMapping을 작성하고, 개발자의 Aggregate 항목이 어떤 Components 항목을 참여시킬지 선택합니다. 렌더링된 출력에 나타나는 리소스는 Aggregate, Release, 어노테이션 바인딩 중 하나에 있는 선언으로, 또는 Aggregate 쪽 컴포넌트 유형이 선택한 Recipe 작성으로 거슬러 올라갑니다.
합성은 작성자가 선언한 형태를 프로바이더별 출력 형식으로 변환합니다. 컨테이너 맵으로 작성된 Workload 스펙은 Kubernetes Pod 스펙, Compose 서비스 블록, Terraform 모듈 중 어느 것으로도 렌더링될 수 있습니다. 변환은 프로바이더가 주도하지만, 리소스는 작성자의 Workload 선언으로 거슬러 올라갑니다.
거버넌스 소켓은 연결마다 역할을 가지며, 연결이 빌드에 무엇을 할 수 있는지를 정하는 것은 플러그인의 종류가 아니라 역할입니다. 판정 역할로 연결된 거버넌스 플러그인 — IR 그래프(ir-verdict)나 렌더링된 아티팩트(render-verdict)를 검토하는 것 — 은 빌드를 거부할 수는 있지만 변경할 수는 없습니다. 그런 판정이 리소스 추가를 원하면, 작성자가 직접 리소스를 추가하도록 해결 방법을 가리키며 빌드를 실패시킵니다. 호스트는 판정의 출력을 수락 또는 거부로만 읽고 결코 변경으로 적용하지 않으므로, 요청받지 않은 채 그래프를 규정 준수 상태로 다시 쓰는 일 — 바로 이 불변 조건이 금지하는 유령 인프라 — 은 판정 역할에서 나올 수 없습니다. 변환 역할(label-transform 또는 annotation-transform)로 연결된 거버넌스 플러그인은 좁고 명시적인 예외입니다. 이를 연결하는 운영자는 — 옵트인으로, 워크스페이스의 plugins.governance 구성을 통해 — 그 변환을 선언한 것이므로, 변환이 만드는 변경은 몰래 하는 주입이 아니라 어노테이션 기반 확장과 같은 지위를 갖는 명시적 선언입니다. 차이는 초대에 있습니다. 요청되지 않은 판정은 빌드를 다시 쓸 수 없지만, 명시적으로 연결된 변환은 운영자가 요청했기 때문에 다시 쓸 수 있습니다. 변환은 렌더링된 출력을 형성하므로 출력을 형성하는 모든 플러그인과 마찬가지로 잠금 파일에 고정됩니다. 적용되는 변환은 pull 시점에 확정되므로, 이를 바꾸려면 빌드 사이에 조용히 바뀌는 것이 아니라 다시 pull해야 합니다. 판정은 어떤 출력도 형성하지 않으므로 고정되지 않습니다.
5. Aggregate 항목이 작성 표면이며, Release 항목은 values:를 선언할 수 없다
Release 스키마는 values: 블록을 기계적으로 금지합니다. 운영자는 Release 쪽에서 Component 항목이나 Feature 항목에 values를 쓸 수 없습니다. 이것은 JSON Schema 수준의 스키마 강제이며 — 사회 계약도, 관례도 아닙니다 — 요란하게 드러납니다. 모든 엔터티 문서는 로드될 때 해당 종류의 스키마에 따라 검증되므로, values:를 포함한 Release 문서는 조용히 무시되지 않고 파일과 문제의 키를 지목하는 진단과 함께 빌드를 중단시킵니다.
그렇다고 값이 모든 환경에서 동일하다는 뜻은 아닙니다. 환경별 변형을 위해 지원되는 경로는 매개변수 끌어올리기(Parameter Hoisting)입니다.
- 개발자가 Aggregate 항목에 타입이 지정된
parameters.*필드를 노출합니다. - Component 쪽
values템플릿이 이를 참조합니다:storage_size: "{{ .parameters.db_size }}". - Release 쪽에서 매개변수를 채웁니다:
parameters: { db_size: "100Gi" }. - 렌더링된 출력에는 환경별 값이 반영됩니다.
어떤 값을 환경별 변형을 위해 노출할지(parameters 선언)와 그 값이 컴포넌트 값으로 어떻게 흘러가는지(템플릿 참조)에 대해서는 Aggregate 항목이 유일한 진실 공급원으로 남습니다. Release 항목은 채울 뿐, 재정의하지 않습니다.
같은 불변 조건을 보호하는 제약이 두 가지 더 있습니다.
- Release 항목이
extends를 사용할 때aggregate:포인터를 선언하는 것은 스키마로 금지됩니다. 자식 Release 항목은 부모와 동일한 개발자 의도(Developer Intent)를 배포해야 합니다. - Release 항목은 Aggregate 항목이 선언하지 않은 컴퓨팅을 도입할 수 없고, 개발자가 선언한 엣지의 대상을 바꿀 수도 없습니다. Architect 역할이 선언한 소켓 범위 안에서 Release 항목은 기존 컴포넌트 사이의 엣지를 연결하고 구성할 수 있습니다. 개발자가 연결한 엣지에 엣지별
infra를 설정하거나, 선언되었지만 바인딩되지 않은 소켓으로 들어가는 엣지를 기존 컴포넌트에 연결합니다. 엣지별values를 선언하거나(이는 Aggregate 항목에 남습니다), Component 쪽usesSchema가 선언하지 않은 소켓을 바인딩하거나, 존재하지 않는 컴포넌트를 엣지의 대상으로 지정할 수는 없으며, 각각 빌드를 중단시킵니다. 가운데 절이 어떤 선언을 뜻하는지 유의하십시오. 소켓은 카탈로그 Component 쪽usesSchema에 나타나야 합니다. Aggregate 작성자는 자신의 컴포넌트 유형이 선언하지 않은 소켓을 지정할 수 있지만, Release 표면은 의도적으로 같은 방식으로 열려 있지 않습니다. 운영자는 아키텍처를 만들어 내는 대신 아키텍처 안에서 연결하고 구성합니다.
엣지별 연결 구성의 범위는 소비자입니다. 엣지에 실린 values와 infra는 그 엣지를 작성한 노드의 렌더링 컨텍스트에만 나타나며, 대상의 컨텍스트에는 결코 나타나지 않습니다. 따라서 컴포넌트 자체의 렌더링 출력은 다른 컴포넌트가 그에 대해 만드는 연결과 무관하게 불변입니다. 대상으로 향하는 엣지를 연결하거나 구성해도 대상의 Recipe 항목이 렌더링하는 내용은 결코 흔들리지 않습니다. 그 연결이 보이는 유일한 곳은 대상에 연결된 Feature 항목입니다. 그 FeatureRecipe 항목은 어떤 컴포넌트가 대상을 사용하는지 읽을 수 있으므로, 그것이 내보내는 리소스 — 예를 들어 선언된 호출자만 정확히 허용하는 정책 — 는 연결을 따르지만 대상 자체의 출력은 따르지 않습니다. 그 경우에도 엣지별 values와 infra는 소비자 쪽에 남습니다.
6. WebAssembly ABI 경계: 도메인별 지능은 Wasm 안에 있다
Go 호스트 바이너리에는 클라우드별 로직이나 인프라 로직이 전혀 없습니다. 모든 도메인별 지능, 템플릿 렌더링, 서식 지정은 내장된 Wazero 런타임이 실행하는 WebAssembly 플러그인 안에만 엄격하게 존재합니다. Go 호스트는 파이프라인을 조율하고, 각 소켓이 지닌 인코딩으로 페이로드를 메모리 포인터 형태로 ABI를 가로질러 Wasm 게스트에 전달합니다.
여기서 두 가지 따름 정리가 나옵니다.
- Provider 전용 로직(Helm 전용 렌더링, Terraform 전용 서식 지정, Compose 전용 병합)은 결코 Go 컴파일러 코어에 존재하지 않습니다. 컴파일러는 Recipe 항목이
spec.capability에 선언한 프로바이더 이름을 이를 처리하는 프로바이더 렌더링 Plugin 항목으로 해석하고 노드를 그 플러그인으로 디스패치하며, 변환 자체는 전적으로 Wasm 게스트에서 실행됩니다. 호스트에는 표준 프로바이더를 위한 프로바이더별 Go 코드가 없으므로 프로세스 안에서 대체할 것이 없습니다. 처리하는 Plugin 항목으로 해석되지 않는 프로바이더 이름은 어떤 내장 기본값을 렌더링하는 대신 빌드를 중단시킵니다. - 정책 로직(보안 규칙, 규정 준수 검사, FinOps 계산)은 결코 Go 컴파일러 코어에 존재하지 않습니다. 정책은 기업이 옵트인하는 Wasm 거버넌스 소켓에 속합니다. 즉 빌드를 수락하거나 거부하기 위해 판정 역할(
ir-verdict/render-verdict)로 연결된 플러그인, 또는 레이블이나 어노테이션을 형성하기 위해 변환 역할(label-transform/annotation-transform)로 연결된 플러그인입니다.
ABI 경계는 Go 코어를 작고, 감사 가능하며, 클라우드에 종속되지 않게 유지합니다. 프로바이더의 렌더링 로직을 바꾸는 것은 Wasm 아티팩트를 교체하는 일이지, Aggrega 자체를 다시 컴파일하는 일이 아닙니다.
7. 관심사 분리(4개 도메인 분할) — 감옥이 아닌 지침
Aggrega 설계 지침은 작성을 네 개의 도메인으로 나눕니다.
- Developer Intent — Aggregate.
- Platform Architect — Component 및 Feature 카탈로그 엔터티.
- Platform Ops — Recipe, FeatureRecipe, Plugin(프로바이더 렌더링 Plugin 포함).
- Platform Operator — Manifest, Release.
잘 작동하는 일반적인 배포는 이 분할을 따릅니다. 개발자는 물리 인프라가 아니라 애플리케이션 의도를 작성하고, Ops 담당자는 애플리케이션 로직이 아니라 물리 인프라를 작성합니다. Aggrega 시스템은 이렇게 사용되도록 설계되었으며, 공식 문서, 예제, 표준 라이브러리 카탈로그는 이 분할에 맞추어 작성되어 있습니다.
4개 도메인 분할은 컴파일러 강제가 아니라 지침이자 설계의 틀입니다. 컴파일러는 (불변 조건 1에 따라) 주관이 없습니다. 사용자는 다음을 자유롭게 할 수 있습니다.
- 역할을 합치기(한 사람이 Aggregates 항목과 Recipes 항목을 모두 작성).
- 관심사를 섞기(기업 카탈로그가 요구할 때 Architect 역할이
core/*Components 항목에 규정 준수 레이블을 직접 하드코딩). - 도메인 경계를 넘기(레거시 코드가 요구할 때 개발자가 매개변수 끌어올리기를 사용해 인프라 관심사를 Aggregate 항목에 주입).
컴파일러는 스키마 검증을 통과하는 어떤 작성 패턴도 받아들입니다. 아키텍처는 모범 사례를 장려하며, 컴파일러가 실제로 거부하는 도메인 횡단은 스키마 수준 제약(불변 조건 5의 Release 항목 values: 금지 등)뿐입니다. 그 밖의 모든 분리는 카탈로그 작성자가, 그리고 기업이 옵트인한 경우 Wasm 거버넌스 소켓이 지키는 사회 계약입니다.
8. 결정적 출력
동일한 입력이 주어지면 컴파일러는 바이트 단위로 동일한 출력을 생성합니다. 같은 카탈로그에 대해 같은 Aggregate + Release + Manifest 조합을 두 번 컴파일하면 바이트 단위로 같은 렌더링 아티팩트가 나옵니다.
이것은 GitOps 도구와 diff 기반 검토 워크플로가 의존하는 계약입니다. 입력을 바꾸지 않은 풀 리퀘스트는 렌더링된 출력에 아무런 diff도 만들지 않아야 합니다. 입력을 바꾼 풀 리퀘스트는 그 변경이 의미하는 diff만 보여야 합니다. 불필요한 재정렬도, 타임스탬프 변동도, 맵 반복으로 인한 부산물도 없어야 합니다.
결정적 출력은 세 가지 원칙으로 유지됩니다.
- 작성자 순서의 맵: 반복 순서가 렌더링된 출력에 영향을 줄 수 있는 모든 맵은 순서가 있는 맵 컨테이너를 사용하여, 반복이 해시 순서가 아니라 작성자의 선언 순서를 따르도록 합니다.
- 작성자가 템플릿 입력을 통해 명시적으로 주입하지 않는 한, 렌더링된 아티팩트에 실제 시각이나 무작위 내용이 들어가지 않습니다.
- 렌더링은 순수합니다. 같은 입력으로 같은 Wasm 게스트를 호출하면 같은 출력이 생성됩니다.
컴파일러의 --trace 플래그(language-reference/cli/aggrega-build.md 참조)는 작성자와 운영자에게 이 불변 조건을 검증할 수단을 제공합니다. --trace를 켜고 같은 입력을 두 번 컴파일하면 바이트 단위로 동일한 트레이스 덤프가 생성되며, 패스별 diff가 있으면 회귀 지점을 찾아낼 수 있습니다. 결정성은 릴리스 시점의 속성만이 아닙니다. 노드별 트레이스 레이아웃을 통해 컴파일러의 모든 중간 상태에서 관찰할 수 있습니다.
결정적 출력은 GitOps 루프에서 Aggrega 시스템을 진실 공급원으로 안전하게 사용할 수 있게 해 주는 계약입니다.
해석 티어 전반의 불변성 범위
바이트 단위로 동일한 출력이라는 보장의 범위는 잠금 파일에 고정된 아티팩트, 즉 잠금 파일이 다이제스트를 기록하는 레지스트리 아티팩트를 통해 해석된 엔터티(3단계 엔터티 해석 모델의 레지스트리 티어)입니다. 빌드가 Release 정의가 경로로 지정한 파일(./ 또는 ../로 시작하는 로컬 경로)이나 워크스페이스 카탈로그 디렉터리의 엔터티(워크스페이스 및 캐시 티어의 catalog_dirs:)를 읽는 경우, 불변성은 그 파일들이 빌드 사이에 바뀌지 않는 것에 달려 있습니다. 잠금 파일은 워크스페이스 카탈로그 디렉터리의 엔터티를 그 문서와 그것이 선언한 파일들의 다이제스트로 기록하므로, pull 이후 바뀐 엔터티가 있으면 빌드는 이를 렌더링하지 않고 중단됩니다. 단 한 가지 예외가 있습니다. Manifest 항목이 어떤 Component 또는 Feature 항목의 이름이기도 한 참조로 지정한 Recipe 또는 FeatureRecipe 항목은 그 참조 아래에 해당 Component 또는 Feature 항목으로 기록되므로, 그 입력은 잠금 안에서 옆에 있는 고정 항목으로만 유지되고 자체 문서의 수정은 감지되지 않습니다. 파일을 원래대로 유지하는 것은 소스 관리 시스템(일반적으로 Git)의 책임입니다.
기반 파일이 두 번의 컴파일 사이에 바뀐 로컬 경로 참조는, 컴파일러 입력의 형태가 바뀌지 않았더라도 렌더링된 출력에 정당한 diff를 만듭니다. 결정적 출력 보장은 유지되지만(같은 바이트 입력 → 같은 바이트 출력), 로컬 파일이 바뀌었기 때문에 입력이 달라진 것입니다. 모든 소스에 대해 빌드 간 불변성이 필요한 카탈로그는 아티팩트를 로컬 경로나 워크스페이스 디렉터리에서 읽는 대신 레지스트리에서 잠금 파일로 고정된 캐시로 가져옵니다. 잠금 파일이 바이트 동일성의 기준점입니다.