콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

게시 표면

모든 Aggrega 카탈로그 YAML에는 카탈로그 배포를 위해 엔터티를 설명하는 통일된 메타데이터 필드 집합이 있습니다. 누가 유지 관리하는지, 어떤 라이선스로 배포되는지, 소스가 어디에 있는지, 어떤 키워드로 검색되는지를 나타냅니다. 이 필드들을 합쳐 게시 표면이라고 합니다. 게시 표면은 카탈로그 게시자와 도구 사용자가 의존하는 메타데이터 어휘이며, labels-and-annotations.md에 설명된 콘텐츠 측의 metadata.labels / metadata.annotations 메커니즘과는 구별됩니다.

이 페이지에서는 게시 표면 필드, 코퍼스 전반의 설명 필드 목록(엔벌로프 설명, 인스턴스 설명, 필드 수준 설명), maintainer 필드의 의도된 용도와 검증된 소비자, 그리고 엔터티별 필수 필드의 비대칭(각 엔터티가 현재 어떤 필드를 요구하는지, 어떤 비대칭이 의도된 것인지)을 설명합니다.

게시 표면 필드

다음 필드는 모든 Domain 2(Component, Feature) 및 Domain 3(Recipe, FeatureRecipe, Plugin) 엔터티에 나타나며, 재사용 가능한 모듈로서의 Aggregate에도 나타납니다. Manifest와 Release에도 나타나지만, 의미가 축소됩니다(카탈로그 게시가 아닌 워크스페이스 귀속).

필드타입목적소비자
descriptionstring사람이 읽을 수 있는 엔터티 요약편집기 호버 카드(aggrega serve), 어시스턴트가 호출하는 describe 도구(aggrega mcp), 게시된 아티팩트의 검색 가능한 어노테이션(aggrega push), aggrega inspect
maintainers객체 배열엔터티 소유자(name, email, url)IR의 Component 노드에 있는 노드별 catalog_metadata
licensestring법적 준수(일반적으로 SPDX 식별자)IR의 Component 노드에 있는 노드별 catalog_metadata
repositorystring (URL)소스가 있는 Git 저장소IR의 Component 노드에 있는 노드별 catalog_metadata — 그 밖에는 읽는 곳이 없음
homestring (URL)문서 / 위키 URLIR의 Component 노드에 있는 노드별 catalog_metadata — 그 밖에는 읽는 곳이 없음
keywords문자열 배열검색용 태그IR의 Component 노드에 있는 노드별 catalog_metadata — 이를 소비하는 검색 인덱스는 없음

여섯 필드는 모두 이를 가지는 모든 엔터티에서 선택 사항입니다. 이 필드 전체를 생략한 카탈로그 작성자도 유효한 YAML을 만듭니다. 게시 표면은 카탈로그 배포를 위한 엔터티용이며, 내부용 엔터티는 아무런 영향 없이 이를 생략할 수 있습니다.

소비자 열은 현재 제공되는 기능을 빠짐없이 나열한 것이며, 그 결과 중 두 가지는 무엇을 작성할 가치가 있는지를 바꾸므로 분명히 밝혀 둘 만합니다.

  • description은 읽는 곳이 둘 이상인 유일한 필드입니다. aggrega serve는 Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest 및 네 가지 라이브러리 종류(SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary)의 호버 카드에 이를 렌더링하며, Plugin이나 Release에는 렌더링하지 않습니다. aggrega mcp가 제공하는 describe 도구는 모든 종류의 엔터티에 대해 이를 반환합니다. aggrega push는 이를 검색 가능한 어노테이션으로 게시된 아티팩트에 기록합니다. aggrega inspect는 모든 종류에 대해 엔터티 헤더 아래에 이를 출력하며, 다른 게시 표면 필드는 출력하지 않습니다.
  • repository, home, keywords는 검증되고 전달되지만, IR 너머에서 이를 읽는 곳은 없습니다. 어떤 목록 화면, 카탈로그 사이트, 검색 인덱스도 이를 소비하지 않습니다. 이를 작성하면 엔터티와 함께 이동하고 IR 출력과 거버넌스 정책에서 읽을 수 있는 출처 정보가 기록되지만, 엔터티를 어디에서든 찾을 수 있게 만들지는 않습니다.

지원 중단(deprecation)은 게시 표면 필드가 아닙니다. 엔터티는 게시 이후 레지스트리에 해당 엔터티에 대한 마커를 기록하여 지원 중단됩니다. 이 마커는 심각도(warning, error 또는 retracted), 사유, 대체 항목을 담은 서명된 마커이며 pull 시점에 검증됩니다. 이후 lockfile을 읽는 모든 화면이 이를 보고하며, build.halt_on_deprecated_severity는 빌드도 중지할지 여부만 결정합니다. 마커는 엔터티 자체의 YAML에 작성되지 않으며, 그 이유는 구조적입니다. 게시된 아티팩트는 불변이므로, 게시 시점에 아티팩트에 고정된 플래그로는 나중에 내려진 결정을 표현할 수 없습니다. aggrega inspect가 카탈로그 엔터티에 대해 출력하는 지원 중단 알림은 이름으로 해석하는 모든 종류에 대해 마커에서 가져옵니다.

IR 소비 — 노드별 catalog_metadata

컴파일러는 각 Component의 게시 표면 필드를 해당 노드의 catalog_metadata 블록으로 전달하며, 이는 실행이 반환하는 IR 그래프(aggrega inspect <release> --ir-graph)에서 확인할 수 있습니다. 이 블록에는 maintainers, license, repository, home, keywords가 들어 있으며, 이는 IR이 전달하는 다섯 필드입니다. description은 여기에 포함되지 않습니다. IR 그래프 계약을 기반으로 만든 도구는 카탈로그 YAML을 다시 읽지 않고 여기에서 메타데이터를 읽습니다.

Component 노드에만 해당합니다. 이 블록은 노드의 component 타입을 카탈로그에서 Component로 조회하여 채워지므로, Feature, Recipe, FeatureRecipe 또는 Plugin의 게시 표면은 IR에 도달하지 않습니다. 이러한 엔터티는 필드를 가지고 있고 필드도 검증되지만, 이들로부터 생성되는 IR 노드는 없습니다.

소스 Component의 모든 게시 표면 필드가 비어 있거나 0이면 catalog_metadata는 IR JSON에서 완전히 제거됩니다. 즉 블록은 빈 값으로 출력되지 않고 생략됩니다. 따라서 같은 입력은 같은 간결한 출력을 내며, 이로써 실행 간 IR diff가 안정적으로 유지됩니다.

거버넌스 정책은 이 블록을 읽을 수 있습니다. ir-verdict 역할로 plugins.governance 아래에 연결된 플러그인은 각 Component 노드의 catalog_metadata를 포함하여 IR 그래프 전체를 노드 단위로 받습니다. 따라서 정책은 노드의 license, repository, home, keywords 또는 maintainers를 기준으로 빌드를 수락하거나 거부할 수 있습니다. 이러한 접근은 거버넌스 소켓에만 해당합니다. provider의 렌더링 플러그인은 catalog_metadata를 포함하지 않는 제한된 노드별 프로젝션을 받으므로, 렌더링 플러그인은 이 필드를 읽을 수 없습니다.

세 가지 설명 유형

description 필드는 엔벨로프에 일관되게 나타나지만, 코퍼스에는 스키마 선언 내부(필드별 설명)와 필러 본문 내부(인스턴스별 설명)에도 설명 형식의 문자열이 있습니다. 서로 다른 세 가지 설명 유형이 공존하며, 아래 표에서 이를 구분합니다.

타입위치작성 주체목적
엔벨로프 설명모든 엔티티의 metadata.description카탈로그 게시자엔티티 전체에 대한 요약으로, 에디터 호버 카드에 표시되고 게시된 아티팩트에 기록됨
인스턴스 설명인스턴스별 선언 옆의 description 필드(예: featuresSchema.<slot>.description, usesSchema.<socket>.description)스키마 작성자슬롯별/소켓별/포트별 설명으로, 선언을 읽는 소비 엔티티 작성자를 위한 것
필드 설명schema: / featuresSchema: / usesSchema: 내용(간결한 형식 또는 전체 JSON Schema YAML) 내부의 JSON Schema 2020-12 description: 주석스키마 작성자스키마와 함께 전달되는 필드별 문서

세 유형은 “description”이라는 단어를 공유하지만 구조적으로 서로 다른 수준에 존재합니다. 엔벨로프 설명은 엔티티 전체에 적용되고, 인스턴스 설명은 스키마 슬롯 내부의 선언에 적용되며, 필드 설명은 타입이 지정된 스키마 내부의 특정 값에 적용됩니다. Component를 작성할 때는 다음과 같이 합니다.

  • Component 엔티티 자체에 대해 metadata.description을 한 번 설정합니다.
  • Component가 선언하는 자격 증명 슬롯마다 featuresSchema.admin_password.description을 한 번씩 설정합니다.
  • schema: 블록 내부에 필드별 description: 주석을 간결한 형식(port: { type: integer, description: "..." }) 또는 전체 JSON Schema YAML로 설정하여, Component의 스키마를 읽는 사람을 위해 각 필드를 문서화합니다.

세 유형은 계단식으로 상속되지 않고 서로 충돌하지도 않으며, 각각 서로 다른 표면에 도달하거나 어디에도 도달하지 않습니다.

  • 엔벨로프 설명 — 위 Consumer 열에 따라 에디터 호버 카드, 게시된 아티팩트의 검색 가능한 주석, 그리고 aggrega inspect에 나타납니다.
  • 필드 설명 — Component 또는 Feature의 호버 카드가 렌더링하는 스키마 발췌문에 그대로 나타납니다. 발췌문은 spec.schema만 다루며 처음 몇 줄로 잘리므로, 블록의 더 깊은 곳에 있는 설명이나 featuresSchema: 또는 usesSchema: 내부의 설명은 여기에 나타나지 않습니다.
  • 인스턴스 설명 — 선언되어 엔티티와 함께 전달되지만, 제공되는 어떤 표면도 이를 단독으로 렌더링하지 않습니다. aggrega inspect는 Component의 소켓과 기능 슬롯을 설명 없이 나열합니다.

maintainer 필드의 의도

maintainers 필드는 객체의 배열을 담으며, 각 객체는 name, email, url을 가집니다. 의도와 확인된 소비자는 다음과 같습니다.

의도(정보 제공 + IR 출처 정보). 이 필드는 카탈로그 게시를 위한 정보 제공용입니다. 아키텍처상의 의도는 “이 카탈로그 엔터티의 책임자는 누구인가”이며, 엔터티와 함께 전달되는 소유권 신호입니다. 이를 연락처 목록으로 표시하는 표면은 없으며, 이를 무엇과 비교하는 내장 검사도 없습니다.

확인된 소비자(노드별 catalog_metadata). 컴파일러는 각 Component의 metadata.maintainers를 IR에서 해당 노드의 catalog_metadata.maintainers로 전달하며, 원본 Component가 이를 선언한 경우 aggrega inspect <release> --ir-graph가 반환하는 그래프에서 확인할 수 있습니다. 이것이 이 필드의 유일한 읽기 주체입니다. ir-verdict 역할로 plugins.governance 아래에 연결된 거버넌스 정책은 그곳에서 이 필드를 보므로, 모든 엔터티가 최소 한 명의 maintainer를 명시한다거나 maintainer의 도메인이 승인된 집합과 일치한다는 등의 소유권 규칙을 카탈로그 YAML이 아니라 IR을 대상으로 표현할 수 있습니다. 그러한 규칙은 기본 제공되지 않으며, 소켓이 그런 규칙이 들어갈 자리입니다.

컴파일러는 JSON Schema의 구조적 형태(name 필수, email과 url은 선택이며 둘 다 문자열) 외에는 maintainer 내용을 강제하거나 검증하지 않습니다. 나열된 maintainer가 실제로 엔터티를 소유하는지, 이메일에 연락이 닿는지, 저장소 커밋이 그중 한 명에 의해 서명되었는지는 카탈로그 거버넌스의 관심사이며, 기본 제공되는 검사 중 어느 것도 이를 평가하지 않습니다. 이는 컴파일러가 아니라 운영자가 연결하는 거버넌스 정책에 속합니다.

필수 필드의 비대칭

Aggrega의 엔터티 종류는 JSON Schema에서 조금씩 다른 필수 필드 집합을 가집니다. 대부분의 비대칭은 의도된 것으로 엔터티의 역할을 반영합니다.

엔터티별 필수 필드는 다음과 같습니다(모든 엔터티가 동일하게 요구하는 apiVersion / kind / metadata.name / metadata.version은 제외):

엔터티추가 필수 필드근거
Componentmetadata.labels.component.aggrega.ai/type레이블 요구 사항은 셀렉터 매칭을 떠받칩니다: usesSchema의 x-aggrega-selector: 어노테이션이 이 레이블로 대상 Components를 필터링합니다. 레이블이 없으면 해당 Component는 로드될 때 거부됩니다
Feature—예약 레이블 요구 사항이 없습니다. Features는 이름과 게시자로 식별됩니다
Recipespec.capability, spec.implementscapability는 provider 디스패치를 제어하고, implements는 Component 바인딩을 제어합니다
FeatureRecipespec.capability, spec.implementsRecipe와 동일
Pluginmetadata.pluginType, spec.abiVersion플러그인이 구현하는 소켓 유형(주소 지정 블록의 일부로, 파생되는 plugin/<pluginType>/<name> 좌표의 <pluginType> 세그먼트를 제공합니다)과 대상 ABI 버전입니다. .wasm 위치는 작성되는 것이 아니라 그 식별자에서 파생됩니다. provider 렌더링 플러그인(pluginType: provider)은 추가로 spec.provider 아래에 변환 계약을 가집니다
Aggregate—components, subsystems, aggregates 중 어느 것도 선언하지 않은 Aggregate는 로드되고 빌드되지만 아무것도 렌더링하지 않습니다
Manifestspec.mappings매핑 계층이 Manifest의 유일한 목적입니다
Releasespec.aggregate, spec.manifest(extends를 선언하는 Release는 aggregate를 쓰지 않으며 manifest를 생략할 수 있음), metadata.environment앞의 두 필드는 빌드를 특정 Aggregate와 Manifest에 고정합니다. environment는 렌더링된 출력에 aggrega.ai/environment 레이블로 기록됩니다

Component 레이블 요구 사항은 동작을 떠받칩니다

component.aggrega.ai/type 레이블은 Aggrega가 어떤 엔터티에든 요구하는 유일한 레이블입니다. 이 요구 사항이 존재하는 이유는 표준 라이브러리의 usesSchema 메커니즘이 "component.aggrega.ai/type=database" 같은 셀렉터 문자열을 담은 x-aggrega-selector: 어노테이션으로 대상 후보를 필터링하기 때문입니다. 셀렉터는 대상의 레이블을 참조하여 유형이 소켓이 허용하는 유형과 일치하는지 판단합니다. Component 스키마가 이를 강제합니다. 레이블을 생략한 Component는 로드될 때 거부되며(E0215), 누락된 키가 명시됩니다.

따라서 이 요구 사항은 게시 표면의 문제(레이블은 카탈로그 검색용이 아닙니다)가 아니라 토폴로지의 문제입니다. 카탈로그 배포를 목표로 하지 않는 내부용 Components를 포함하여 모든 Component가 이 레이블을 가집니다.

Release metadata.environment는 필수입니다

Release 스키마는 metadata.environment를 요구합니다. 이는 빌드가 렌더링된 출력에 aggrega.ai/environment 레이블로 기록하는 문자열입니다.

다른 비대칭

나머지 비대칭(Recipe와 Component의 필수 필드 차이, Manifest의 mappings 요구 사항)은 각 엔터티의 역할을 반영합니다. 모든 엔터티 종류에 걸친 균일한 필수 필드 계약은 제공되지 않습니다. 이 비대칭은 역할 중심 설계에 따른 의도된 것입니다.

상호 참조

  • labels-and-annotations.md — 게시 표면을 보완하는 콘텐츠 측 메타데이터 메커니즘입니다.
  • entities/component.md — Component의 metadata.labels.component.aggrega.ai/type 요구 사항과 schema / usesSchema / featuresSchema 선언입니다.
  • entities/release.md — Release의 metadata.environment 필드와 그 필수 요구 사항입니다.
  • 10-status.md — 메타데이터 엔벨로프의 상태입니다.
  • architecture/02-ecosystem-philosophy.md — 엄격한 API 분할(Strict API Partitioning)과 엔터프라이즈 메타데이터 제품군(Enterprise Metadata Suite)의 설계 프레이밍입니다.
  • architecture/13-catalog-and-registry.md §“Lockfile pinning and artifact immutability” + §“Catalog entity name-shape enforcement” — 불변성 규칙이 게시 시점에 거부하는 항목과, 엔터티 종류별 이름 형태가 검사되는 위치를 설명합니다. 게시 규율 플러그인은 작성자가 aggrega lint를 실행할 때 이를 권고 형태로 보고하며, 빌드와 게시 어느 쪽도 이를 검사하지 않습니다.
  • architecture/11-governance-and-compliance.md §“Inheritance and publishing discipline” — 어떤 거버넌스 규칙이 게시 규율 플러그인에 속하고, 어떤 규칙이 대신 확장하는 Component의 상속에 의해 구조적으로 해결되는지 설명합니다.