사회 계약
Aggrega는 설계상 주관이 없는 컴파일러입니다. architecture/05-invariants.md에 문서화된 기본 불변 조건에 따라 컴파일러는 YAML을 파싱하고, 그래프를 순회하고, 레이블 교집합을 평가하고, 구성 요소 간에 문자열을 전달합니다. 하지만 개발자가 values, parameters, infra, provides, locals에 무엇을 넣는지 단속하지 않으며, 명명 관례, 포트 관례, Architect가 고안한 의미적 레이블을 강제하지 않고, 이름으로 구성 요소의 목적을 추측하지 않습니다. 컴파일러 규칙처럼 들리는 많은 규율은 실제로는 사회 계약입니다. 즉 스키마나 런타임 강제가 아니라 작성 관례로 유지되는 모범 사례입니다.
이 중립성이 어디에서 멈추는지는 분명히 말해 둘 가치가 있습니다. 그 경계는 한 줄이며 지나치게 확대 해석하기 쉽기 때문입니다. 몇몇 키는 Aggrega 자체의 것으로, 예약되어 있으며 허용되는 값이 게시된 스키마에 기록되어 있습니다. 스키마는 이러한 키를 다른 선언된 필드와 같은 방식으로 검사합니다. 플랫폼이 직접 정의하는 키의 값 집합을 선언하는 것은 컴파일러가 작성된 내용에 의미를 부여하는 것이 아니라, 플랫폼이 자신의 키가 무엇을 의미하는지 밝히는 것입니다. 직접 정의한 키 아래에 작성하는 모든 내용은 이 페이지에서 설명하는 그대로 단속되지 않습니다.
이 페이지는 언어의 사회 계약에 대한 표준 목록입니다. 이 페이지에서 계약을 익힌 작성자는 컴파일러가 관례상 잘못된 빌드를 왜 받아들이는지(실제로 받아들입니다. 컴파일러는 관례를 해석하지 않습니다), 그리고 위반을 잡아낼 책임이 어디에 있는지(작성 규율, 리뷰어의 주의, 또는 aggrega lint가 실행하는 린터 플러그인)를 추론할 수 있습니다.
규율의 세 가지 등급
Aggrega의 규율은 규율이 어떻게 강제되는가에 따라 세 가지 등급으로 나뉩니다. 이 분류가 중요한 이유는 규율을 위반했을 때 등급마다 실패 양상이 다르기 때문입니다.
스키마로 강제
이 규율은 로드 시점의 JSON Schema 2020-12 검증으로 강제됩니다(엔티티 엔벌로프의 JSON Schema와 Component 및 Feature 엔티티의 필러 수준 schema: 선언). 위반하면 빌드가 진행되기 전에 치명적 중단이 발생하며, 컴파일러는 진행을 거부합니다. 스키마로 강제되는 규율을 위반하려는 작성자는 해당 필드와 제약 조건을 가리키는 명시적인 검증 오류를 보게 됩니다.
예: 엔티티 엔벌로프의 필수 필드(apiVersion / kind / metadata.name / metadata.version), metadata.version에 대한 SemVer 정규식, 예약된 component.aggrega.ai/type 레이블의 닫힌 값 집합, Release 스키마의 values: 블록에 대한 기계적 금지(Invariant 5에 따름), Release에서 extends와 aggregate를 함께 쓰는 경우의 거부(Single Source of Truth 불변 조건), 입력 종류 구성 계약을 강제하는 Recipe 형태 규칙.
스키마로 강제되는 규율은 언어가 제공하는 가장 강력한 보장입니다. 컴파일러는 이를 위반하는 어떤 것도 렌더링하지 않습니다.
정책 플러그인으로 강제
이 규율은 문서화된 소켓 지점 중 하나에서 실행되는 Wasm 플러그인으로 강제됩니다(토폴로지 구성 시의 거버넌스 label-transform 역할, 정적 분석 시의 거버넌스 ir-verdict 역할, 대역 외 linter 소켓). 위반하면 소켓의 게이팅 의미론에 따라 빌드를 중단시키는 정책 실패(대역 내 소켓) 또는 권고 경고(대역 외 소켓)가 발생합니다.
규율은 이를 검사하는 플러그인이 실행되는 곳에서만 이 방식으로 강제됩니다. Wasm 런타임은 문서화된 소켓 지점에서 플러그인을 호출하며, 어떤 플러그인도 검사하지 않는 규율은 관례로 남습니다. aggrega lint가 실행하는 게시 린터는 이 페이지의 관례 하나 중 일부를 검사합니다. 린터 규칙이 검사하는 관례를 참조하십시오. 게시 린터의 어떤 규칙도 밀폐성(Sprig FuncMap은 templates/sprig-functions.md의 결정성 주의 사항에 따라 결정적 출력을 깨뜨리는 헬퍼를 노출함)이나 클라우드 리소스 명명(entities/recipe.md의 “Cloud-resource naming discipline”에 따라 valuesMapping: 출력이 release_name / instance_id 보간 없이 클라우드 리소스 이름 필드를 참조하는 Recipes)을 검사하지 않습니다. 직접 만든 린터 플러그인은 둘 중 어느 것이든 검사할 수 있습니다.
Wasm 플러그인 계약 표면과 배치 기준(린터 소켓 대 거버넌스 판정 역할)은 plugins/plugin-contract.md를 참조하십시오.
관례로 유지
이 규율은 오직 작성 규율과 리뷰어의 주의로만 유지됩니다. 컴파일러는 강제하지 않으며, 어떤 스키마도 위반을 거부하지 않고, 어떤 Wasm 플러그인도 이를 표시하지 않습니다. 작성자는 문서에서 규율을 배우고, 아키텍처의 형태가 그에 의존하기 때문에 이를 따르며, 실수를 잡아내는 데는 PR 리뷰에 의존합니다. 위반은 컴파일 시점에 어떤 신호도 만들지 않습니다. 빌드는 성공하고, 렌더링된 출력은 컴파일러가 아는 한 정상 동작하며, 규율 위반은 다운스트림 도구나 런타임 동작이 그 관례에 의존할 때에만 드러납니다.
관례로 유지되는 규율은 작성자가 문서에서 반드시 배워야 하는 핵심 목록입니다. 컴파일러는 이를 해석하지 않습니다. 이를 잘못 지켜도 빌드는 깨지지 않지만, Aggrega가 의존하는 아키텍처의 형태는 깨집니다. 이 페이지의 대부분은 이들을 문서화합니다.
관례
다음 사회 계약은 관례로 유지됩니다. 각 항목은 규율, 관례가 문서화된 위치, 위반 시의 실패 양상을 명시합니다. 각 항목은 어디에 있든 번호를 유지합니다. 계약 3인 예약 접두사 규율은 어노테이션 키에 대해 린터 규칙이 검사하며 린터 규칙이 검사하는 관례에서 설명합니다.
1. 컴포넌트에 맞는 운영 유형 선택
예약된 component.aggrega.ai/type 레이블은 컴포넌트가 어떤 종류의 것인지를 나타내며, 보편적인 클라우드 기본 요소로 이루어진 닫힌 집합 server, worker, task, function, stateful-server, resource에서 값을 가져옵니다. 이 집합에 속하는지 여부는 관례로 유지되는 것이 아니라 스키마로 강제됩니다. Aggrega가 이 키와 허용되는 값을 정의하고, Component 스키마가 그 값을 열거하며, 다른 값을 가진 문서는 로드 시 거부됩니다. E0215, 즉 entity-envelope-invalid 조건이 해당 레이블을 지목하고 허용되는 값을 나열합니다. 이 항목이 다루지 않는 것이 바로 이 거부입니다.
관례로 남는 것은 눈앞의 컴포넌트에 값 중 어느 것이 맞는가입니다. 관계형 데이터베이스에 server가 아니라 stateful-server 레이블이 붙었는지, 큐 소비자가 task가 아니라 worker인지는 아무것도 검사하지 않습니다. 셀렉터는 발견한 값을 의미를 해석하지 않고 그대로 평가합니다. Component를 작성하는 Architect는 인프라가 그것을 어떻게 다뤄야 하는지를 설명하는 값을 고르며, 다운스트림 셀렉터, 정책 플러그인, Wasm 렌더링 플러그인은 모두 그 선택이 정직하다는 데 의존합니다.
자체 축으로 분류하기. 닫힌 집합은 이 하나의 예약 키만 규율하며 그 밖에는 적용되지 않습니다. Aggrega가 정의하지 않는 분류(티어, 데이터 영역, 서비스 등급, 또는 운영 기본 요소의 더 세분화된 구분)가 필요한 카탈로그는 예약 키 옆에 자체 레이블 키를 추가합니다. Component 스키마는 문자열 값을 가진 추가 레이블 키를 모두 허용하고 같은 셀렉터 메커니즘이 이를 읽으므로, acme.aggrega.ai/storage-tier: oltp가 component.aggrega.ai/type: stateful-server와 나란히 놓이고 Feature의 appliesTo나 소켓의 selector는 둘 중 어느 것이든 대상으로 삼을 수 있습니다. 확장은 Aggrega의 키 안의 값이 아니라 항상 자체 키에서 이루어집니다.
문서 위치: architecture/02-ecosystem-philosophy.md (운영 온톨로지) + labels-and-annotations.md (접두사 규율) + errors/sentinels.md (E0215).
실패 양상: 집합에 속하지만 컴포넌트에 맞지 않는 값은 그 레이블을 읽는 모든 것을 오도합니다. server 레이블이 붙은 데이터 저장소는 stateful-server를 선택하는 Feature나 소켓에서 거부되며, 이때의 중단은 잘못된 레이블이 아니라 셀렉터를 지목합니다. 또한 그 레이블을 읽는 정책 플러그인이나 렌더링 플러그인은 이를 상태 없는 컴퓨트로 취급합니다. 그러한 독자만 그것을 보는 경우 빌드는 성공하며, 실수는 렌더링된 아티팩트가 클러스터에 도달한 뒤에야 드러납니다.
2. 세 버킷 .context.annotations.* 분리
캐스케이드된 어노테이션은 .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate라는 세 개의 이름 있는 버킷에 들어가며, 각각 다른 의도를 담습니다. 규율의 목표는 다음과 같습니다. release는 “이 컴포넌트가 실행되는 위치, Ops가 관리”, catalog는 “이 컴포넌트가 무엇인지, Architect가 작성”, aggregate는 “이 컴포넌트가 하는 일, Developer가 작성”입니다.
컴파일러는 버킷 경계를 강제하지 않습니다. 세 버킷은 평평한 string → string 형태를 공유하며, Recipe의 템플릿은 세 버킷을 모두 읽을 수 있고, Release 경계 어노테이션이 인지 메타데이터로 해석되거나 카탈로그 어노테이션이 infra:로 라우팅되는 것을 막는 장치는 없습니다. 이 분리는 작성자가 어노테이션을 올바른 버킷에 쓰고 리뷰어가 버킷 간 누출을 잡아내는 것으로 유지됩니다.
문서 위치: labels-and-annotations.md (세 버킷 분리는 Social Contract입니다).
실패 양상: 버킷 의도의 구분에 의존하는 라우팅 로직(예: .context.annotations.release.aggrega.ai/region을 Terraform region 필드로 라우팅하는 Recipe)은 작성 의도와 관계없이 버킷에 나타나는 어노테이션을 조용히 소비합니다. 빌드는 성공하지만, 렌더링된 출력에 의미상 잘못된 값이 담길 수 있습니다.
4. Recipe provides: 자기 완결성
Recipe provides: 템플릿은 노드 자신의 데이터만 참조합니다. 즉 .values, .infra, .context.instance_id, 노드의 provider가 보고하는 경우의 .context.rendered_name, 노드의 해석된 .locals, 그리고 정적 문자열입니다. provides 평가는 해당 템플릿을 임의의 순서로 실행하므로 .context.inject와 .context.uses 참조는 금지됩니다. 노드 간 데이터를 읽으면 위상 순회 순서에 결합되는데, 설계는 이를 의도적으로 피합니다. .locals는 허용 범위에서 벗어나지 않고 포함됩니다. 노드의 locals는 같은 단계의 프리앰블에서 provides보다 먼저 해석되고 노드 로컬이므로, 이를 읽어도 순서 면에서 비용이 들지 않습니다. locals 블록이 선언하지 않은 키를 지정하면 중단됩니다.
이는 두 부분으로 이루어진 규칙이며, 각 부분은 어디서 검사되는지를 명시합니다. 앞부분은 컴파일러가 검사합니다. provides 평가는 템플릿이 실행되기 전에 각 템플릿을 그 컨텍스트가 정의하는 루트의 긍정 허용 목록과 대조하여 검사하므로, .context.inject / .context.uses 읽기는 빈 값으로 렌더링되지 않고 명시적 오류와 함께 중단됩니다. 이 규칙은 templates/expansion-matrix.md 6행에도 문서화되어 있습니다. 뒷부분은 관례가 유지합니다. 더 넓은 패턴(provides는 공개, locals는 비공개)은 관례에 기반합니다.
문서 위치: templates/expansion-matrix.md 6행 + vocabulary/data-pillars.md “provides:와 locals: — 공개 면 대 비공개 면”.
실패 양상: 금지된 참조가 provides:에 직접 나타나면 컴파일러는 템플릿 평가 시점에 이를 감지하고 빌드를 중단합니다. 더 넓은 공개 대 비공개 규율(provides: 키를 통해 내부 상태를 노출하지 않는 것)은 관례일 뿐입니다. provides:를 Recipe 내부 네임스페이스처럼 다루는 작성자는 호출자가 의존하는 계약을 만들어 내며, 리팩터링은 호환성을 깨는 변경이 됩니다.
5. 결정성 — 렌더 경로 템플릿의 비밀폐(non-hermetic) 헬퍼
Aggrega의 결정적 출력 불변식(architecture/05-invariants.md의 불변식 8)은 바이트 단위로 동일한 입력에 대해 바이트 단위로 동일한 출력을 요구합니다. Sprig의 전체 FuncMap은 주변 상태를 읽는 헬퍼를 노출합니다(벽시계 판독기 now / date, 난수 생성기 randAlpha / uuidv4, 환경 판독기 env / expandenv, 네트워크 리졸버 getHostByName). 렌더링 출력에 기여하는 템플릿에서 이러한 헬퍼를 호출하는 작성자는 결정성 계약을 깨뜨립니다.
컴파일러는 비밀폐 헬퍼의 사용을 감지하거나 차단하지 않습니다. Sprig FuncMap은 templates/sprig-functions.md “Determinism caveat”에 따라 이를 노출하며, 이 규율은 작성자가 렌더 경로 템플릿에서 해당 헬퍼를 피하고 리뷰어가 PR 리뷰에서 그 사용을 잡아냄으로써 유지됩니다.
문서 위치: templates/sprig-functions.md “Determinism caveat”.
실패 양상: 동일한 입력에 대한 실행마다 빌드 출력이 달라집니다. 이 불일치는 다운스트림 도구(ArgoCD, Flux)가 커밋된 매니페스트와 클러스터 상태 사이에서 예상치 못한 드리프트를 발견하는 GitOps diff 시점에, 또는 동일한 입력의 두 컴파일이 서로 다른 아티팩트를 생성하는 감사 시점에 드러납니다.
게시 린터의 어떤 규칙도 템플릿에서 비밀폐 헬퍼 호출을 검사하지 않습니다. 헬퍼의 이름은 템플릿에 쓰여 있으므로 직접 만든 린터 플러그인이 이를 찾을 수 있습니다(린터 규칙이 검사하는 관례 참조).
6. 필라 경계(벽이 아닌 이정표)
필라 경계는 언어 차원의 강제가 아니라 작성 규율입니다. 템플릿 엔진은 자기 완결성 규칙으로 명시적으로 금지되지 않는 한(예: Recipe provides: 및 source:에서 .context.inject / .context.uses를 읽는 경우) 모든 위치에서 필라 간 읽기를 허용합니다. 작성자는 다음을 따라야 합니다.
- 인지적 페이로드(개발자가 작성한 의도)는
.values에서 읽습니다. - 물리적 사이징(Ops가 작성한 사이징)은
.infra에서 읽습니다. - 컴포넌트 간 포인터 문자열은
.context.uses.<alias>.provides.<key>에서 읽습니다. - 하이드레이션 이후 전달 파이프는
.context.inject에서 읽습니다.
템플릿 엔진은 읽기를 제한하지 않습니다. .infra.replicas를 읽어 values: 필드를 구동하는 Recipe 템플릿은 동작하며, 필라 간 경로를 막는 것은 없습니다. 규율의 목표는 이정표입니다. 경계는 런타임 제약이 아니라 작성 의도(데이터를 누가 소유하는지)를 나타냅니다.
문서 위치: vocabulary/data-pillars.md “Pillar boundaries and authoring discipline”.
실패 양상: 필라 간 누출 — 개발자의 인지적 페이로드에 물리적 사이징 세부 정보가 들어가거나, Ops가 작성한 사이징에 인지적 메타데이터가 들어갑니다. 빌드는 성공하지만, 작성자가 필라를 우회함에 따라 네 영역의 작성 분담이 시간이 지나며 흐려지고, 필라와 데이터 흐름 간의 대응이 약해지면서 다운스트림 유지 관리가 어려워집니다.
7. Workload containers.<name>.variables의 이중 소스 의미
variables: 맵은 Go 템플릿 표현식을 통해 서로 다른 두 데이터 소스를 혼합합니다. 개발자 필라 리터럴(.values / .infra / .locals를 읽는 항목)과 컴포넌트 간 파이프 데이터(.context.inject.env.<KEY>를 읽는 항목)입니다. 작성자는 값이 컴포넌트 로컬인지, 컴포넌트 간에서 파생된 것인지에 따라 항목마다 하나의 소스를 선택합니다.
컴파일러는 두 소스를 구분하지 않으며, 둘 다 렌더링된 Deployment의 동일한 Kubernetes env: 목록으로 흘러 들어갑니다. 이중 소스 의미는 작성 시점에만 존재합니다. 이 규율은 의도를 명명하는 것(이 항목은 컴포넌트 로컬, 저 항목은 컴포넌트 간 파생)이며, 이를 통해 향후 유지 관리자가 어떤 항목이 어떤 inject 하이드레이션 출력에 의존하는지 읽을 수 있습니다.
문서 위치: entities/workload.md “Field-semantics essentials”(variables).
실패 양상: 두 소스를 구분하지 않는 작성자는 “어떤 항목이 어떤 대상의 provides:에 결합되어 있는지”에 대한 추적을 잃습니다. 대상의 provides: 키를 리팩터링하면 inject 파이프를 통해 읽던 호출자의 모든 variables: 항목이 조용히 깨집니다.
8. 클라우드 리소스 명명 규율
클라우드 리소스 이름(S3 버킷 이름, RDS 데이터베이스 식별자, IAM 역할 이름, CloudFormation 스택 이름 — 클라우드 공급자에서 전역 네임스페이스를 차지하는 값을 가진 모든 필드)을 내보내는 Recipes는 동일한 Recipe가 여러 Releases나 컴포넌트 인스턴스에서 실행될 때 충돌을 피하기 위해 렌더링된 이름에 {{ .metadata.release_name }} 및/또는 {{ .context.instance_id }}를 연결해야 합니다.
컴파일러는 valuesMapping: 출력에서 이러한 보간이 없는 클라우드 리소스 이름 필드를 검사하지 않습니다. 이 규율은 Recipe 작성자(대상 공급자에서 어떤 필드가 전역적으로 고유한 리소스를 명명하는지 아는 사람)와 리뷰어(PR 리뷰에서 이름 없는 리소스 패턴을 잡아내는 사람)에 의해 유지됩니다.
문서 위치: entities/recipe.md “Cloud-resource naming discipline”.
실패 양상: 동일한 Aggregate의 두 Releases(prod-billing와 staging-billing)가 모두 같은 전역 이름을 가진 리소스를 배포하려 하고, 두 번째 배포는 런타임에 클라우드 측 거부로 실패합니다. Aggrega 빌드는 성공하며, 배포 실패는 두 번째 Release가 적용될 때에야 드러납니다.
게시 린터의 어떤 규칙도 클라우드 리소스 이름 필드에 필요한 보간이 있는지 검사하지 않습니다. 직접 만든 린터 플러그인은 검사할 수 있습니다(린터 규칙이 검사하는 관례 참조).
9. Component 세분성 — Component당 하나의 응집된 서비스
Component는 하나의 응집된 서비스를 모델링합니다. 즉 노출된 단일 서비스, 또는 한 서비스의 워크로드와 그 내부 전용 헬퍼 워크로드를 함께 모델링합니다. 차트가 다른 컴포넌트가 독립적으로 의미 있게 use할 수 있는 서비스들 — 특히 Aggrega가 이미 자체 Component로 모델링하는 데이터베이스, 캐시, 메시지 브로커 같은 외부 인프라 — 를 묶고 있다면, 표준 라이브러리는 제품 전체를 하나의 불투명한 Component로 감싸는 대신 서비스별 Components를 하위 aggregate 모듈(spec.aggregates + exportedComponents)로 구성합니다. 규율은 다음과 같습니다. 하나의 Component 안에 여러 워크로드가 있는 것은 괜찮으며, 독립적인 사용 가능성이 하나의 Component를 스택으로 나누는 기준선입니다.
컴파일러는 이 세분성에 구애받지 않습니다. 스키마 검증을 통과하는 것은 무엇이든 렌더링하며, Component의 Recipe가 몇 개의 서비스를 묶는지, 그중 하나가 독립적으로 사용 가능한지는 검사하지 않습니다. 다섯 개 서비스로 된 제품을 단일 Component로 감싸는 작성자는 컴파일러가 아무 불평 없이 수용하고 렌더링하는 Component를 만들어 냅니다. 이 관례는 작성 규율과 리뷰어의 주의로 유지됩니다.
문서 위치: ../../architecture/06-data-taxonomy-and-composition.md (One coherent service per Component — the single-workload boundary).
실패 양상: 여러 서비스를 하나로 감싼 모놀리식 래핑은 빌드에 성공하지만, 묶인 서비스들은 토폴로지, 셀렉터, 정책에 보이지 않으므로 독립적으로 확장하거나 교체하거나 의존할 수 없습니다. 나중에 모놀리스를 서비스별 Components로 리팩터링하면 감싸인 단일 노드를 참조하던 모든 소비자에게 호환성을 깨는 변경이 됩니다.
관례가 존재하는 이유
이 관례들은 모두 설계상 작성 규율이지만, 스키마나 Wasm 정책으로 그중 어느 것이든 강제할 수 있습니다. 계약 유형별 근거는 다음과 같습니다.
확장성. 예약 접두사 규율(계약 3)은 표준 라이브러리의 어휘를 설명할 뿐, 유효한 어휘 전체를 설명하지 않습니다. 엔터프라이즈 카탈로그는 표준 라이브러리를 확장하기 위해 자체 접두사와 레이블 키를 작성합니다. 접두사 관례를 스키마로 강제하면 “표준 라이브러리의 규율”이 “언어가 허용하는 유일한 형태”로 바뀌게 되며, 이것이 바로 아키텍처가 의도적으로 피하는 벽입니다. 운영 유형 축(계약 1)은 다른 표면에서 같은 확장성을 유지합니다. Aggrega가 정의하는 예약 키는 닫혀 있고 스키마로 강제되는 집합을 가지며, 카탈로그는 Aggrega의 키 안에 값을 추가하는 대신 그 옆에 자체 레이블 키를 추가하는 방식으로 확장합니다. 스키마가 검사하는 것은 스키마가 소유한 하나의 키의 값 집합이며, 열려 있는 것은 그 밖의 모든 키로, 카탈로그 자체의 어휘가 바로 그곳에 있습니다.
AOT 순수성. 클라우드 리소스 명명 규율(계약 8)과 결정성 규율(계약 5)은 필드가 클라우드 리소스 이름인지 또는 비밀폐(non-hermetic) 헬퍼 호출인지 판단하기 위해 템플릿 내용을 들여다봐야 합니다. AOT 순수성(불변 조건 2)은 컴파일러가 런타임 상태에 의존하지 않도록 합니다. 정적 템플릿 검사는 가능하지만(린터 플러그인은 엔터티의 템플릿을 작성된 그대로 읽습니다), 이를 코어 컴파일러 안에서 수행하면 컴파일러 내부 로직이 도메인별 작성 관심사와 결합됩니다. 아키텍처는 불변 조건 6(Wasm ABI 경계)에 따라 이러한 검사를 컴파일러 밖의 Wasm 플러그인으로 옮깁니다.
작성 유연성. 필러 경계 규율(계약 6)과 이중 소스 variables 의미(계약 7)는 런타임 제약이 아니라 작성 패턴을 설명합니다. 같은 템플릿 구문으로 규율을 지키는 패턴도, 규율을 어기는 패턴도 표현할 수 있습니다. 규율을 런타임 검사로 만들려면 컴파일러가 접근할 수 없는 작성 의도를 해석해야 합니다. 아키텍처는 이 관례를 런타임 불변 조건이 아니라 작성자가 배우는 문서로 취급합니다. Component 세분성(계약 9)도 여기에 속합니다. 엔터프라이즈는 카탈로그가 선호하는 어떤 세분성으로든 제품을 감쌀 수 있으며, 불변 조건 1에 따라 내용에 중립적이고 주관이 없는 컴파일러는 번들된 워크로드가 독립적으로 사용 가능한지 알 방법이 없으므로, 하나의 일관된 서비스라는 경계는 스키마 벽이 아니라 작성 규율로 남습니다. 운영 유형의 선택(계약 1)도 같은 형태입니다. 스키마는 어떤 값이 존재하는지 정하지만, 주어진 구성 요소를 어느 값이 설명하는지는 인프라가 그것을 어떻게 다뤄야 하는지에 대한 모델링 판단이며, Recipe나 values 블록의 어떤 것도 그 판단이 옳았는지 컴파일러에게 알려 주지 않습니다.
두 부분으로 나뉜 강제. Recipe provides: 자기 완결성(계약 4)은 부분적으로 컴파일러가 강제합니다. 렌더 경로는 provides: 템플릿에서 .context.inject / .context.uses 읽기를 감지하고 중단합니다. 더 넓은 공개 대 비공개 규율(내부 상태를 노출하지 않기)은 관례에 기반합니다. 작성 의도 없이는 어떤 문자열이 Recipe 내부에 남아야 하는지 컴파일러가 판단할 수 없기 때문입니다.
세 가지 경로가 중요한 이유는 각 경로가 위반을 잡아낼 책임이 어디에 있는지 알려 주기 때문입니다. 스키마로 강제: 컴파일러. 정책 플러그인으로 강제: 이를 검사하는 플러그인(실행되는 경우). 관례로 유지: 작성자와 리뷰어. 이 경로를 숙지한 작성자는 어떤 실수를 컴파일러가 잡아내고 어떤 실수가 다운스트림 도구나 런타임까지 조용히 통과하는지 이해합니다.
린터 규칙이 검사하는 관례
aggrega lint가 실행하는 게시 린터는 이 페이지의 관례 하나를 부분적으로 검사합니다. 아래 계약 3의 어노테이션 키입니다. 그 결과는 권고이며, 린터가 다루지 않는 관례의 나머지 부분은 위의 항목들과 마찬가지로 관례로 유지됩니다.
게시 린터의 어떤 규칙도 이 페이지의 다른 관례를 검사하지 않습니다. 그중 두 가지는 위반이 엔터티에 쓰여 있으므로 린터 규칙으로 검사할 수 있습니다. 결정성(계약 5), 즉 비밀폐 헬퍼를 호출하는 템플릿과, 클라우드 리소스 명명(계약 8), 즉 release_name / instance_id 보간 없이 클라우드 리소스 이름을 짓는 valuesMapping: 출력입니다. 예약 접두사 아래의 레이블 키(계약 3)도 마찬가지입니다. 워크스페이스는 게시 린터와 나란히 plugins.linter 아래에 자체 린터 플러그인을 연결하여 이들 중 어느 것이든 검사할 수 있습니다. The discipline rules에 게시 린터가 가진 규칙이 나열되어 있습니다.
나머지 관례(1, 2, 4, 6, 7, 9)는 작성자가 의도한 바에 달려 있으며, 어떤 규칙도 작성된 내용에서 그것을 읽어 낼 수 없습니다. 버킷 분리는 확장성에 따른 것이므로(엔터프라이즈 카탈로그가 재정의함) 스키마 강제는 그 유연성과 충돌합니다. 스키마가 값 집합을 확정한 뒤 운영 유형 축에 남는 부분, 즉 컴포넌트에 맞는 프리미티브를 고르는 일은 작성 의도에 따른 것입니다. 잘 고른 운영 유형과 잘못 고른 운영 유형은 둘 다 컴파일러가 허용하는 값이므로 컴파일러는 둘을 구분할 수 없습니다. 필러 경계 규율과 이중 소스 variables 의미 체계는 작성 의도에 따른 것으로, 컴파일러는 템플릿 구문만으로 의도를 판단할 수 없습니다. Recipe provides: 자기 완결성은 부분적으로 강제되며, 더 넓은 공개 대 비공개 규율은 작성자가 어떤 키를 내부에 두려 했는지에 달려 있는데, Recipe의 어디에도 그것은 명시되어 있지 않습니다. Component 세분성 역시 작성 의도에 따른 것으로, 묶인 워크로드를 독립적으로 사용할 수 있는지는 컴파일러가 Recipe 내용에서 읽어 낼 수 없는 모델링 판단입니다.
3. 예약 접두사 규율
어노테이션과 레이블 키는 <namespace>/<name> 형태를 따릅니다. 다섯 개의 예약 접두사에는 특정 작성 규칙이 있습니다. aggrega.ai/(플랫폼 전용), feature.aggrega.ai/(공식 Feature 단축키), component.aggrega.ai/(Component 고유 특성), aggregate.aggrega.ai/(Aggregate 모듈 식별), <any-other-domain>/(기업 / 커뮤니티)입니다.
컴파일러는 카탈로그 엔터티나 Release에서 예약 접두사 아래에 작성된 어노테이션을 거부하지 않습니다. aggrega.ai/ 아래의 키를 주장하는 Manifest 어노테이션 바인딩이나 Recipe 출력 레이블만 빌드를 중단시킵니다. 플랫폼 어휘 밖에서 aggrega.ai/internal-billing-tag: "..."를 선언하는 기업은 컴파일러가 받아들이고 버킷 시스템을 통해 캐스케이드하는 어노테이션을 만들어 내며, 실제 aggrega.ai/internal-billing-tag를 도입하는 이후 플랫폼 업데이트와 조용히 충돌합니다.
문서 위치: labels-and-annotations.md (접두사 규율) + providers/well-known-annotations.md.
실패 양상: 예약 접두사 아래의 사용자 정의 어노테이션은 같은 이름의 향후 플랫폼 어노테이션과 충돌합니다. 순서에 따라 플랫폼의 예상 동작이 기업이 작성한 값을 조용히 덮어쓰거나 그 값과 공존합니다.
aggrega lint가 실행하는 게시 린터는 카탈로그 엔터티의 어노테이션 키 중 aggrega.ai/ 아래에 있으면서 플랫폼의 잘 알려진 어노테이션이 아닌 것과, Feature가 아닌 엔터티에서 feature.aggrega.ai/ 아래에 있는 것을 권고 결과(E0277)로 표시합니다. 레이블 키, 다른 예약 접두사, 엔터티의 metadata.annotations 밖에 있는 어노테이션(예: Release가 쓰는 것)은 검사되지 않으므로, 이들에 대해서는 규율이 관례로 남습니다.
상호 참조
architecture/05-invariants.md— Aggrega의 “컴파일러는 내용에 중립적이다”라는 관점의 근거가 되는 여덟 가지 기본 불변 조건입니다. 각 관례는 이 중 하나 이상과 긴장 관계에 있습니다.architecture/02-ecosystem-philosophy.md— 운영 온톨로지의 전체 설계 근거입니다.vocabulary/labels-and-annotations.md— 사회 계약으로서의 세 버킷 분리, 예약 접두사 규율입니다.vocabulary/data-pillars.md— 이정표로서의 필러 경계,provides:와locals:의 공개 대 비공개 구분입니다.templates/sprig-functions.md— 비밀폐적 헬퍼를 명시하는 결정성 주의 사항입니다.entities/recipe.md— 클라우드 리소스 명명 규율과 작성 예시입니다.entities/workload.md— Workloadvariables:의 이중 소스 의미론입니다.templates/expansion-matrix.md— 컴파일러가 강제하는 규칙으로서의 Recipeprovides:자기 완결성입니다.plugins/plugin-contract.md— linter 소켓의 배치 기준입니다.cli/aggrega-lint.md— 게시 린터의 규칙과 직접 만든 린터 연결 방법입니다.