카탈로그와 레지스트리
이 장에서는 OCI(Open Container Initiative) 카탈로그를 통해 플랫폼이 엔터프라이즈 전반으로 확장되는 방식을 정의합니다. 카탈로그가 구성되는 방식, 참조가 해석되는 방식, 엔터티가 게시되고 고정되는 방식, 그리고 카탈로그 엔터티가 따르는 이름 형태를 다룹니다.
Aggrega 카탈로그: 레지스트리 분류 체계와 해석
Aggrega 컴파일러는 추상적인 개발자 의도(도메인 1)를 구체적인 운영 현실(도메인 3)로 해석하기 위해 엄격하게 타입이 지정된 OAM 기반 레지스트리를 사용합니다. 원활한 개발자 경험을 유지하면서 개방적이고 분산된 생태계를 지원하기 위해, 모든 스키마, 인프라 바인딩, 프로그래밍 가능한 정책, 어댑터 플러그인은 표준화된 OCI(Open Container Initiative) URI 분류 체계를 따릅니다. 모든 카탈로그 엔터티는 URI로 주소 지정이 가능하므로, aggrega pull은 Release에 필요한 엔터티를 캐시로 가져와 잠금 파일에 고정하고, 빌드는 그곳에서 이를 읽습니다. 개발자의 로컬 작업 공간에는 카탈로그의 사본이 아니라 자신의 Aggregate 및 Release 파일만 들어 있습니다.
1. 핵심 디렉터리 구조(카탈로그)
표준 라이브러리의 aggrega-catalog 폴더(및 이를 준수하는 모든 서드파티 카탈로그)는 관심사의 분리를 물리적으로 강제하도록 구성되어 있습니다. 이 구조는 추상 인터페이스를 구체적인 인프라 구현과 명시적으로 분리합니다.
Components와 Features의 경우 URI 세그먼트는 파일 시스템 경로 세그먼트와 1:1로 대응합니다. Components는 세 세그먼트 URI({publisher}/{category}/{name})를 사용하며, 여기서 category 세그먼트는 닫힌 집합인 인지적 카테고리 중 하나를 담습니다. 이는 컴포넌트의 component.aggrega.ai/category 레이블과 같은 단어입니다(1:1 디렉터리 미러이며, 게시 린터의 category-matches-directory 규칙으로 검사됩니다). Features는 평면 구조({publisher}/{name})를 유지합니다. 수가 적고 천천히 늘어나기 때문입니다. 운영 온톨로지 분류(stateful-server, server 등)는 디렉터리 구조가 아니라 항상 component.aggrega.ai/type 레이블에 있습니다. 인지적 기능 레이블(datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …)은 그 위에 동작 하위 집합을 덧붙입니다. 허브 웹 UI는 필터링과 검색에 레이블을 사용하며, 카테고리는 파일 시스템 탐색과 카탈로그의 둘러보기 축 모두에 쓰입니다.
아래 트리는 내용은 예시이지만 형태는 정확합니다. 엔터티가 완전하게 그려진 곳에서는 리프 파일까지 내려가므로, 다이어그램에서 실제 전체 경로를 읽어 낼 수 있습니다. 어느 디렉터리 수준이 어느 URI 세그먼트를 담는지, 필수 버전 세그먼트가 어디에 있는지, 각 엔터티 종류가 리프에서 어떤 파일 이름을 사용하는지 알 수 있습니다. 카탈로그의 전체 내용이 아니라 수준마다 몇 개의 항목만 보여 줍니다. ...는 생략을 나타내며, 그 옆에 적힌 이름은 같은 수준의 추가 항목입니다.
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraform컴포넌트 카테고리는 닫힌 집합이며, 파일 시스템이 아니라 이 집합이 카테고리의 기준입니다. 아직 엔터티가 없는 카테고리 값은 예약된 어휘입니다. 둘러보기 축이 안정적으로 유지되고 작성자는 향후 컴포넌트가 어디에 들어갈지 알 수 있으므로, 빈 선반은 채워져야 할 공석이 아니라 올바른 상태입니다. 카탈로그에는 자리 표시자 파일이 없으므로, 그러한 값의 디렉터리는 첫 엔터티가 들어올 때 생성됩니다.
모든 카테고리, 각 카테고리가 담는 것, 해당 엔터티가 일반적으로 갖는 운영 type 값, 존재하는 디렉터리를 담은 권위 있는 목록은 카탈로그 관례 가이드의 Component Categories 섹션이며, 이 가이드는 그것이 관할하는 표준 라이브러리 카탈로그와 함께 게시됩니다.
type 축은 운영 기본 요소만 담습니다. 인지적 어휘는 여기에 절대 나타나지 않으며, 게시된 Component 스키마가 이 예약된 키가 가질 수 있는 값을 열거하므로 그곳에 인지적 단어를 쓰면 문서를 로드할 때 거부됩니다. 세 축의 분리는 다음과 같습니다. 운영 type(인프라가 컴포넌트를 다루는 방식), 인지적 category(그것이 무엇인지이며 디렉터리로 미러링됨), 역할별 기능 레이블(동작 하위 집합)입니다. 엔터티는 category: datastore에 더해 자체 제품 정체성이 갖는 datastore.aggrega.ai/engine 값을 가지므로, core/datastore/qdrant는 vector를, core/datastore/redis는 kv를 가지며 두 축 모두 쿼리할 수 있습니다. 작성자가 구성하는 내용에 따라 참 여부가 달라지는 기능은 카탈로그에 전혀 담기지 않습니다. 이는 개발자가 선언한 values를 읽는 거버넌스 소켓의 label-transform 역할이 컴파일 시점에 주입합니다. AI 전용 카테고리에는 ai- 접두사가 붙고, 이중 용도 카테고리는 접두사 없이 나타나며 AI 특성은 기능 레이블로 표현됩니다. 카테고리는 컴파일러가 분류하는 방식이 아니라 사용자가 탐색하고 둘러보는 방식을 기준으로 선택됩니다. 카테고리 어휘와 기능 레이블은 컴파일러가 셀렉터와 대조할 뿐 의미를 부여하지 않는 것입니다. 컴포넌트의 이름은 카테고리를 반복하지 않습니다. 표준 라이브러리의 OpenAI 모델은 core/ai-model/openai-model이 아니라 core/ai-model/openai입니다.
2. 분할 스키마와 브리지 합성 파이프라인
토폴로지 소켓 선언을 둘러싼 Component별 상용구를 없애기 위해, Aggrega는 검증을 두 부분으로 나누고 각각을 그 대상이 있는 곳에서 검사합니다.
usesSchema(선언적 YAML). 카탈로그 엔터티가 제공하는 토폴로지 소켓을 선언하고 각 소켓에 계약을 부여합니다. Go CLI는 이를 기본적으로 읽어 정적 분석 중 레이블 매칭을 위한selector:문자열을 추출하고 허용된inject메커니즘을 검증합니다. 각 소켓 항목은 선택적required: true필드(기본값false)를 지원합니다. 이 필드를 설정하면 해당 소켓에 의존성이 선언되지 않은 경우 컴파일러가 검증 오류를 냅니다. 이는featuresSchema항목의required: true의미론에 대응하는 소켓 버전이며, 둘 다 빌드를 중단합니다. 여기에 소켓을 선언하는 것은 표준 라이브러리 카탈로그가 하는 방식이며 여전히 더 나은 방법이지만, 개발자가 엣지를 그릴 수 있는 유일한 방법은 아닙니다. Aggregate 작성자는 자신의 컴포넌트에서 이usesSchema가 선언하지 않은 소켓을 지정할 수 있으며,usesSchema를 전혀 선언하지 않은 엔터티에서도 마찬가지입니다. 이러한 임시 소켓에는 셀렉터도,inject허용 목록도, 엣지별 스키마도 없는데, 바로 이것들을 담을 항목이 여기에 없기 때문입니다. Feature 연결의uses와 Release의 엣지별uses는 그렇게 열려 있지 않으며, 둘 다 선언된 소켓만 지정할 수 있습니다. 전체 계약과 임시 소켓이 포기하는 것은 dependency-resolution §“Domain 2: The Split Schema”를 참조하십시오.- 디슈가링. 개발자가 YAML 배열 축약형(
uses: databases: ["db1"])을 사용하면 CLI가 이를 맵({"db1": {"target": "db1"}})으로 정규화합니다. - 브리지 합성. 컴파일러는
featuresSchema:슬롯 테이블을 JSON Schema 2020-12 조각으로 투영합니다. 연결 슬롯마다 하나의 속성이 있어 해당 슬롯에 바인딩될 수 있는 채움의 형태를 기술하며,inject허용 목록을 선언하는 슬롯에는x-aggrega-inject:확장 키워드가 붙습니다. JSON Schema 검증은 구조 검증 중 확장 키워드를 무시하며, 조각에서 이를 다시 읽어 들이는 것은 없습니다. 슬롯의 허용 목록이 필요한 검사는 슬롯 자체를 읽습니다.usesSchema:소켓 테이블은 어떤 조각으로도 투영되지 않습니다. 소켓의selector:와inject:는 Architect가 작성한 타입 지정 YAML에 그대로 남아 거기서 읽히며, 소켓의 엣지별valueSchema:/infraSchema:는 래핑되어 독립적으로 컴파일되고, 그 주위에 만들어진 제약은 없습니다. - 합성. 플랫폼 아키텍트는
values,infra,provides를 정의하는 엄격한schema:선언(컴팩트 형식 또는 완전한 JSON Schema 2020-12)을 작성합니다. 이 선언은 엔터티 자신의 계약이며 독립적으로 컴파일됩니다. 슬롯 조각도 소켓 테이블도 여기에 합쳐지지 않습니다. 각 표면은 그 대상이 있는 곳에서 검사되므로, 소켓 오류는schema:블록 내부의 경로가 아니라 아키텍트가 작성한 소켓 항목을 기준으로 보고되며, 아키텍트는 여전히uses상용구를 작성하지 않습니다.
예시 — 소켓 선언과 컴파일러가 이를 처리하는 방식: Platform Architect의 YAML
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}컴파일러가 이를 처리하는 방식
소켓 테이블은 있는 그대로 타입 지정 YAML로 읽힙니다. selector: 문자열은 네이티브 레이블 매칭 엔진으로 전달되고, inject: 목록은 해당 소켓을 통과하는 엣지가 지정할 수 있는 전달 메커니즘을 제한합니다. schema: 블록은 엔터티 자신의 values / infra / provides 계약으로서 별도로 컴파일됩니다. Static Analyzer는 Architect가 작성한 소켓 항목에서 selector: 문자열을 Feature 엔터티의 appliesTo / appliesToAnyOf와 함께 읽고, 각 대상의 metadata.labels에 대해 레이블 매칭을 평가하여 노드 간 타입 안전성을 검증합니다.
usesSchema의 Kubernetes 스타일 셀렉터
Go 컴파일러의 네이티브 레이블 매칭 엔진은 표준 Kubernetes 스타일 선택 의미론(쉼표로 AND, in()으로 OR, !=/notin()으로 NOT)을 사용하여 셀렉터 문자열을 평가합니다. 이 동일한 엔진과 동일한 셀렉터 문자열 문법이 Feature 연결 셀렉터(appliesTo, 그리고 appliesToAnyOf의 각 항목)도 평가합니다. 셀렉터 계층은 엄밀히 토폴로지 게이트이며, 필러별 schema: 선언이 values, infra, provides 내용을 독립적으로 검증합니다. Go 컴파일러가 토폴로지 구성 단계에서 토폴로지 엣지를 그린 후, Static Analyzer는 Architect가 작성한 소켓 항목에서 selector 문자열을 읽고 대상 노드의 Catalog labels에 대해 평가하여 노드 간 타입 안전성을 검증합니다.
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"엔진이 여섯 가지 요구 형식 중 하나로 읽을 수 없는 셀렉터(빈 요구, 공백이나 =, !, (, ) 및 쉼표 중 하나를 포함한 키, 닫히지 않은 집합)는 다른 셀렉터로 읽히는 대신 그것이 지키는 각 엣지에서 빌드를 중단시킵니다. 셀렉터 문법에 형식과 모든 거부 사례가 나와 있습니다.
3. 스키마 형식과 합성
엄격한 검증과 표준 카탈로그 메타데이터(작성자, 버전, 설명)를 모두 제공하기 위해, Domain 2(인터페이스)와 Domain 3(구현) 정의는 YAML 엔벌로프로 작성됩니다. Domain 2는 압축 형식(기본값, 약 15개 키워드, JSON Schema 2020-12로 기계적으로 변환됨) 또는 전체 JSON Schema YAML로 표현된 내장 schema: 선언을 사용합니다.
모든 카탈로그 YAML이 엔벌로프를 반복하는 이유. 엔벌로프(apiVersion, kind, metadata 블록)는 본문이 아무리 짧더라도 모든 카탈로그 파일(Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin)의 맨 위에 나타납니다. 이 반복은 의도된 것입니다. 각 파일은 독립된 아티팩트로서 파싱, 검증, 린트, 검사가 가능하도록 설계되어 있습니다. OCI 레지스트리에서 가져오거나, CI 샌드박스에 넣거나, 서드파티 편집기에서 연 단일 파일은 하위 도구가 그 파일이 어떤 종류의 엔티티를 나타내는지, 어떤 스키마 버전이 적용되는지 식별할 수 있을 만큼의 자기 기술을 담고 있어야 합니다. 디렉터리 위치가 엔벌로프를 대신하는 일은 없습니다. 모든 파서, 검증기, 린터는 엔티티의 종류와 스키마 버전을 엔벌로프에서 읽습니다. 비용은 파일마다 생기는 기계적인 상용구이고, 이점은 독립 도구 보장이 OCI 배포 표면, 로컬 파일 시스템, IDE / CI / inspect 표면 전반에서 유지된다는 것입니다. 작성자는 새 카탈로그 콘텐츠를 작성할 때 기존 파일에서 엔벌로프를 복사하거나, aggrega scaffold <kind>에서 시작합니다. 이 명령은 apiVersion과 kind가 채워진 해당 종류의 시작 문서를 출력합니다.
DRY(Don’t Repeat Yourself) 원칙을 유지하기 위해 카탈로그는 서로 다른 두 가지 합성 메커니즘을 사용합니다.
- 공유 SchemaLibrary 항목(문서 간
$ref:): 재사용 가능한 JSON Schema 정의는 SchemaLibrary 카탈로그 엔티티(Tier 3)에 저장됩니다. 이 정의는 어떤 소비자 Component 또는 Feature 스키마에서든 문서 간$ref:(<library>#/schemas/<entry>, 호스트 없음, 버전은 lockfile에서 가져옴)를 통해 식별자로 참조됩니다. 체인은 컴파일 시점에 탐색됩니다. 라이브러리 엔티티의 작성 형태는 entities/schemalibrary를, 해석 의미론은 vocabulary/cross-document-ref를 참조하십시오. - 단일 상속(
extends): 완전한 component 기준선이 필요하면 엔티티는extends: "URI"속성을 사용할 수 있습니다. Go 컴파일러는 부모 체인을 재귀적으로 읽고 YAML 메타데이터를 깊은 병합합니다(충돌 시 레이블을 덮어쓰고 배열은 이어 붙임). 그런 다음 두 카탈로그 종류는 데이터 기둥에서 갈라집니다. Feature의schema:는 JSON Schema 2020-12 합성 규칙에 따라 기반의 스키마와 합성됩니다. 확장하는 Component는 기둥 콘텐츠를 전혀 작성하지 않습니다. 리터럴 마커schema: inherited를 작성하면 체인의 모든 깊이에서 기반이 작성한 그대로의schema:블록을 받습니다. 이러한 Component가 대신 합성하는 것은 구조입니다. 부착 슬롯(featuresSchema), 토폴로지 소켓(usesSchema), 자기 주입 허용 목록(inject), 이름 있는assertions가 모두 체인을 따라 병합됩니다. 기반-자식 component 확장 예제는 entities/component를, 상속이 구성에 의해 해결하는 것과 게시 규율 규칙으로 남는 것은 governance-and-compliance §“Inheritance and publishing discipline”를 참조하십시오.
기반-자식 component 확장 예제는 entities/component를, 완전한 예제가 포함된 Recipe 포인터-매퍼 작성은 entities/recipe를 참조하십시오.
4. 워크스페이스 설정(.aggrega-config.yaml)
워크스페이스 루트의 .aggrega-config.yaml 파일은 프로젝트의 워크스페이스 구성으로, go.mod나 package.json처럼 소스 관리에 적합한 워크스페이스 자체의 선언입니다. .aggrega/ 디렉터리는 관례상 소스 관리에서 제외합니다. node_modules/나 .terraform/처럼 .gitignore에 등록하십시오.
workspace 섹션은 루트 마커입니다. 이 섹션이 있으면 워크스페이스 루트로 표시되며, 루트를 정의하는 카탈로그 디렉터리, 즉 catalog_dirs와 Release에 자체 카탈로그 디렉터리를 부여하는 releases 맵만 담습니다. 그 밖의 모든 설정은 최상위에 있습니다. 많은 설정은 단일 값이고, 나머지는 한 관심사의 설정을 하나의 키 아래 모은 섹션입니다. 모든 필드는 선택 사항이며 문서화된 기본값이 있습니다. 최상위 키의 완전한 최신 목록은 각각의 타입, 기본값, 의미와 함께 schema/other/aggrega-config의 스키마에서 생성됩니다. 아래 예제는 루트 마커와 몇 가지 단일 값 설정을 함께 보여 줍니다.
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootsigning: 블록은 aggrega push --sign과 aggrega sign이 사용하는 아티팩트 서명 기본값을 최상위(전역)와 레지스트리별 양쪽에서 담습니다.
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pem필드별 우선순위는 CLI 플래그 > 레지스트리별 signing > 전역 signing > 공공 기본값입니다. Fulcio와 Rekor는 기본적으로 공공 Sigstore 인스턴스를 사용하므로 선택 사항입니다. timestamp_url에는 기본값이 없습니다. 키리스 신뢰 타임스탬프는 Rekor의 투명성 로그 포함에서 오며, RFC3161 타임스탬프 기관은 옵트인입니다(사용하려면 timestamp_url 또는 --timestamp-url에 전체 엔드포인트를 설정). 보안: signing: 블록에는 비밀 자료가 없습니다. OIDC ID 토큰은 절대 구성 필드가 아니며(단기 비밀로, 서명 시점에 제공됨. 대화형 터미널에서는 브라우저 흐름으로, GitHub Actions에서는 워크플로에서 획득하며, 그 밖의 경우에는 --identity-token으로 전달하거나 AGGREGA_IDENTITY_TOKEN 또는 SIGSTORE_ID_TOKEN으로 내보냄), 개인 키도 절대 인라인으로 두지 않습니다. key_path는 키 파일의 경로입니다. 이는 검증 측과의 의도적인 비대칭으로, 검증 측은 인라인 공개 키를 고정하지만 서명 측에서는 항상 키 경로만 사용합니다.
벤더링된 카탈로그가 없는 루트는 workspace: {}로 표시합니다. catalog_dirs 목록은 공유 카탈로그가 형제 디렉터리에 있는 모노레포 구성을 지원합니다. 컴파일러는 각 디렉터리를 순서대로 확인합니다. offline: true 플래그는 모든 네트워크 접근을 막습니다. 컴파일러는 로컬 경로와 캐시만 사용하며, 엔티티를 로컬에서 찾지 못하면 중단합니다. 섹션형 설정은 각각 하나의 관심사를 모읍니다. 그중에는 빌드 시점 엄격도 조절과 작성 힌트, 각각 플러그인 참조 목록을 받는 워크스페이스 수준 Wasm 부착 소켓(governance, linter, importer, providers, cli), 게시 규율 정책 스위치를 포함한 규칙별 린트 엄격도, 데몬의 파싱 캐시 튜닝과 요청 디스패치 워커 풀 크기, 머신 전체 컴파일된 모듈 저장소의 크기 상한이 있습니다. 또 다른 설정은 서명 및 서명 신뢰 기본값과 데몬 자체의 동작을 담습니다. 모든 최상위 키는 schema/other/aggrega-config에 전부 문서화되어 있습니다.
구성 가능한 캐시는 세 가지이며, 이름은 비슷하지만 범위는 다르므로 잠시 구분해 둘 가치가 있습니다. artifact_cache_dir는 아래에 설명하는 워크스페이스별 디스크 콘텐츠 캐시를 가리킵니다. parse_cache는 데몬이 살아 있는 동안만 존재하는 데몬의 메모리 내 파싱 캐시의 상한을 정합니다. compiled_module_cache는 컴파일된 플러그인 기계어의 디스크 저장소 상한을 정합니다. 플러그인의 컴파일된 형태는 그것을 사용하는 프로젝트가 아니라 플러그인에 따라 달라지므로, 이 저장소는 머신의 모든 워크스페이스가 공유하는 캐시 중 하나입니다.
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the cap머신의 모든 프로젝트가 공유하는 캐시 가운데 디스크 캐시 사용량을 가장 많이 차지하게 될 수 있는 것이 이 저장소입니다. 머신이 실행하는 모든 플러그인이 이곳에 한 번 컴파일되어 보관되기 때문이며, 그래서 상시 크기 상한을 가진 유일한 캐시이기도 합니다. 저장소를 여는 모든 호출은 무엇이든 컴파일하기 전에 상한을 적용하며, 나머지가 상한에 들어갈 때까지 가장 오래전에 컴파일된 항목부터 항목 단위로 통째로 제거합니다. (--disable-plugin-cache로 실행한 빌드는 대신 메모리에 컴파일하므로 저장소를 키우지도 줄이지도 않습니다.) 항목을 제거하는 비용은 나중의 재컴파일뿐이며, 그 덕분에 상한을 낮추는 것도, 같은 머신에서 다른 빌드가 실행 중일 때 상한을 적용하는 것도 안전합니다. 상한은 빌드 하나가 컴파일하는 양보다 크게 설정합니다. 상한은 컴파일 전에 적용되므로, 빌드 하나의 작업 집합보다 작은 상한을 두면 모든 빌드가 같은 모듈을 버리고 다시 컴파일하게 됩니다. 같은 이유로 저장소는 빌드와 빌드 사이에 상한을 넘어 있을 수 있으며, 다음 빌드가 시작될 때 다시 줄어듭니다. aggrega cache status는 저장소의 크기를 보고하고, aggrega cache evict --max-size는 명령줄에 지정한 상한까지 필요할 때 저장소를 줄입니다.
artifact_cache_dir 루트에는 aggrega pull 호출 한 번이 균일하게 채우는 세 개의 병렬 하위 트리가 있으며, 고정된 의존성의 종류마다 하나씩입니다. 카탈로그 엔터티(Components, Features, Recipes, FeatureRecipes, Aggregates, 라이브러리, 그리고 Plugins와 그것이 게시하는 실행 파일)용 <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/(여기서 종류는 엔터티가 게시될 때의 종류이므로, 참조와 버전을 공유하는 서로 다른 종류의 두 엔터티—같은 이름의 Component와 Recipe—는 두 개의 슬롯이 됩니다), Recipe / FeatureRecipe의 spec.source 필드에서 가져온 소스 아티팩트(Helm 차트, compose 조각)용 <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/, 그리고 외부 입력용 <artifact_cache_dir>/inputs/sha256/<hex-digest>입니다. 외부 입력은 provider가 렌더링하는 동안 호스트에 요청하는 원격 문서로, 예를 들어 차트의 values.schema.json에서 URL을 가리키는 $ref가 이에 해당합니다. 각 소스 아티팩트 캐시 슬롯에는 권위 있는 .tgz 아카이브, 빌드가 읽을 때마다 다시 생성되는 파생 extracted/ 디렉터리, 그리고 아티팩트의 {kind, url, version, digest, mediatype, pulled_at} 식별 정보를 기록하는 metadata.yaml 파일이 들어 있습니다. 각 엔터티 캐시 슬롯에는 가져온 그대로의 게시된 아티팩트와 그것을 검증하는 기준인 OCI 매니페스트가 들어 있습니다. 문서가 옆에 있는 파일을 지정할 수 있는 종류—Recipe, FeatureRecipe, Component, Feature—의 슬롯에는 그 아티팩트가 담은 파일을 아티팩트의 콘텐츠 다이제스트로 이름 붙인 디렉터리에 보관하는 파생 extracted/ 디렉터리도 있습니다. 아카이브로 게시된 경우에는 문서와 엔터티가 선언한 파일이, 문서 자체로 게시된 경우에는 문서만이 들어 있습니다(§6). 엔터티의 디렉터리는 소스 아티팩트의 파일과 마찬가지로 읽을 때마다 검증된 아티팩트로부터 그곳에 배치됩니다. 모든 파일은 아티팩트와 대조되고, 그 디렉터리에서 수동으로 변경되거나 추가된 파일은 읽히지 않고 버려지며, extracted/ 아래의 다른 것은 읽히지 않고, 검증에 실패한 아티팩트는 무엇이든 배치되기 전에 거부됩니다. 읽기는 아티팩트와 다른 부분만 다시 쓰므로, 하나의 캐시를 동시에 읽는 빌드들—aggrega serve가 나란히 처리하는 요청들, 또는 하나의 작업 공간에 대한 두 명령—은 각각 건네받은 파일을 온전한 상태로 찾습니다. 12자의 <digest-prefix> 세그먼트는 서로 다른 업스트림 다이제스트로 다시 태그된 같은 {kind, url, version}을 별개의 슬롯으로 구분합니다. 외부 입력에는 그런 슬롯이 필요하지 않습니다. lockfile이 고정한 콘텐츠 다이제스트로 이름 붙인 단일 파일로 저장되므로, 이후 빌드가 읽는 것은 바이트가 도착한 URL이 아니라 고정값으로 주소가 지정됩니다. 이것이 그 빌드가 네트워크가 차단된 상태에서도 입력을 제공할 수 있게 해 줍니다.
이 세 디렉터리 옆에 세 개의 디렉터리가 더 나타날 수 있으며, 어느 것도 고정된 의존성 콘텐츠를 담지 않습니다. index/에는 aggrega registry update가 쓰는 레지스트리별 검색 가능 스냅샷이 들어 있고(§8), signatures/는 검증된 각 서명 번들을 그 자체의 다이제스트 아래에 캐시하므로, 이후의 읽기는 번들을 다시 가져오지 않고 캐시된 blob을 기록된 다이제스트와 다시 대조하며, catalog-snapshots/는 가져오기가 읽은 게시된 카탈로그 스냅샷을 각각 보관합니다(§8). 아카이브와 그 매니페스트는 매니페스트 다이제스트로 이름 붙은 슬롯에 들어 있고, 카탈로그 트리는 읽을 때마다 아카이브에서 펼쳐지며, 다른 것이 지정되지 않은 경우 워크스페이스가 읽는 스냅샷을 가리키는 current 파일도 함께 있습니다.
문서 번들은 여기에 포함되지 않습니다. 번들의 바이트는 게시된 레지스트리와 게시된 버전에만 의존하므로, 머신당 한 번, 같은 사용자별 캐시 루트 아래 컴파일된 모듈 저장소 옆, 그 루트 아래의 docs-bundles/<encoded-reference>/<encoded-version>/에 보관됩니다. 여기에는 번들, 번들을 검증하는 기준인 매니페스트, 그리고 가져올 때 검증된 서명이 들어 있습니다. artifact_cache_dir은 이곳에 미치지 않습니다. 페이지를 읽기 전에 그 서명은 번들의 레지스트리에 대해 읽는 작업 공간 자체의 서명 검사로 다시 검증되므로, 한 작업 공간의 느슨한 설정이 받아들인 사본이 그것을 거부하는 검사를 가진 작업 공간에 제공되지 않습니다. aggrega-explain 및 aggrega-cache를 참고하십시오.
artifact_cache_dir은 작업 공간 루트를 기준으로 작성되며, 명령을 어느 디렉터리에서 호출하든, 어떤 카탈로그 디렉터리를 스캔하든 같은 디렉터리를 의미합니다. 절대 경로 값은 구성을 로드할 때 해당 필드를 지목하는 진단과 함께 거부됩니다. 이 설정을 읽는 모든 곳은 작업 공간 루트를 기준으로 해석하므로 절대 경로는 어느 곳도 도달하지 못하는 위치를 가리키게 되며, 그렇지 않으면 실패가 드러나지 않습니다. pull이 쓰는 캐시가 조용히 빌드가 읽는 캐시가 아니게 되는 것입니다. 캐시는 카탈로그 디렉터리 안에 있어도 되며, 카탈로그 디렉터리는 흔히 작업 공간 루트 자체이므로 기본 레이아웃에서는 실제로 그렇습니다. 캐시가 해서는 안 되는 것은 카탈로그 디렉터리 자체가 되는 것입니다. 카탈로그 스캔은 캐시를 건너뛰므로, 카탈로그 디렉터리이기도 한 캐시 디렉터리는 그 디렉터리의 전체 내용을 모든 스캔에서 빼 버립니다. artifact_cache_dir: .은 작업 공간 루트를 가리키며, 기본 레이아웃에서는 바로 그런 경우이므로 구성을 로드할 때 해당 필드를 지목하는 진단과 함께 거부됩니다. 작업 공간 루트로 귀결되는 다른 모든 표기도 마찬가지입니다. 이 두 형태와 앞서 말한 절대 경로가 구성 검사가 스스로 인식할 수 있는 경우입니다. 다른 카탈로그 디렉터리를 가리키는 값—catalog_dirs에 sub가 나열된 작업 공간에서의 sub—은 아무런 경고 없이 로드되며, 유일한 증상은 그 아래의 엔터티가 더 이상 발견되지 않는다는 것입니다. 따라서 workspace.catalog_dirs에 나열된 모든 디렉터리 밖에 캐시를 두는 것은 구성이 대신 검사해 주는 것이 아니라 구성을 작성하는 일의 일부입니다.
캐시를 건너뛰는 것은 해석 결과물이 작성자가 작성한 것처럼 읽히지 않도록 하기 위함입니다. 캐시 슬롯에는 레지스트리 가져오기가 놓아 둔 바이트가 들어 있으며, 가져온 좌표 아래에 저장되고 lockfile 다이제스트로 보증됩니다. 스캔이 이를 작성된 카탈로그 콘텐츠로 집어 든다면, 아무것도 검증하지 않은 바이트를 작성자가 편집할 수 없는 경로에서 가져오는 셈이 됩니다. 한 가지 결과는 분명히 말해 둘 가치가 있습니다. 캐시에 어떤 lockfile도 고정하지 않은 엔터티가 있다면—중단된 pull이 남겼거나, 수동으로 복사되었거나, Release가 더 이상 참조하지 않아 고립되었거나—그 엔터티는 카탈로그 스캔에 보이지 않으며, 그것에 의존하는 빌드나 검증은 엔터티를 찾을 수 없다며 중단됩니다. 해결책은 Release를 다시 pull하여 엔터티가 lockfile을 통해 해석되고 그 다이제스트가 기록되도록 하는 것입니다. 중단 메시지는 엔터티를 지목하므로 누락된 고정값을 식별할 수 있습니다. 그래도 해석하는 대안은 캐시를 건너뛰는 동작이 막기 위해 존재하는, 검증되지 않은 읽기입니다.
lockfile은 Release별로 존재합니다. release.yaml을 해석하면 그 옆에 release.lock이 작성됩니다(Release 파일의 이름 줄기에 .lock을 붙인 것). aggrega pull은 의존성을 해석하고 lockfile을 작성하며, aggrega build는 이를 읽어 빌드 시점의 레지스트리 상태와 관계없이 고정된 버전을 사용합니다. 머신 간 빌드 재현성이 중요한 워크스페이스는 lockfile을 커밋합니다. 워크스페이스에서 엔티티, 라이브러리, 플러그인 또는 Release 자체가 변경된 후에는 aggrega pull --release <release>가 lockfile을 갱신하여 다른 모든 고정은 유지한 채 변경된 부분만 다시 해석하며, 레지스트리가 새로 제공하는 버전은 aggrega pull --upgrade --release <release>로 채택합니다. lockfile은 해석된 모든 엔티티를 종류, 작성된 그대로의 URI, 해석된 버전, 콘텐츠 다이제스트, 참조 위치와 함께 기록합니다. 종류와 URI가 함께 하나의 항목을 식별하므로, Aggregate와 Manifest가 같은 이름을 공유하는 Release는 각각에 대해 항목을 하나씩 기록하며, 둘 중 어느 쪽을 편집하더라도 pull이 이를 기록할 때까지 다음 빌드가 중단됩니다:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1고정된 각 항목에는 종류 + URI + 해석된 버전 + 콘텐츠 주소 지정 다이제스트가 담깁니다. 다이제스트는 가져올 때마다 검증되며, 고정된 다이제스트와 일치하지 않는 바이트는 무결성 오류로 빌드를 중단시킵니다. 엔티티의 다이제스트는 전송되는 형태의 바이트가 아니라 게시물이 담는 내용, 즉 문서와 그 옆에 선언한 모든 파일(각각의 경로와 바이트)에 대해 계산됩니다. 따라서 같은 엔티티는 카탈로그 디렉터리에서 읽든 레지스트리에서 가져오든, 아카이브가 어떻게 압축되었든, 체크아웃이 파일에 어떤 권한 비트(실행 비트 포함)를 부여했든 같은 다이제스트를 기록합니다. 가져온 내용은 먼저 게시된 바이트에 대한 레지스트리 자체의 다이제스트와 매니페스트를 통해 대조되며, 레지스트리에서 해석된 항목은 그 매니페스트의 다이제스트를 자체 다이제스트 옆에 기록합니다.
5. 3계층 엔티티 해석 모델
컴파일러는 컴파일 중에 만나는 모든 엔티티 참조를 엄격한 단계적 조회로 해석합니다. 세 계층(로컬 경로, 워크스페이스와 캐시, 레지스트리)은 건강한 Aggrega 프로젝트에 공존하는 세 가지 작성 워크플로에 대응합니다. 옆에 있는 파일을 지정하는 Release, 체크인된 카탈로그와 이전에 가져온 캐시를 사용하는 팀, 아직 가져오지 않은 아티팩트를 위해 레지스트리에 접근하는 pull입니다. 같은 단계적 조회 중 워크스페이스와 캐시 계층 및 레지스트리 계층이 Aggregates의 type 필드, Manifest 매핑의 URI 값, Recipes와 FeatureRecipes의 implements 선언, Recipe와 FeatureRecipe 파이프라인 내부의 plugin 참조를 평가합니다. 로컬 경로 계층에는 Release와 그 Manifest가 지정하는 파일만 도달합니다.
로컬 경로. Release의 aggregate, manifest, extends 참조 또는 Manifest의 extends가 ./ 또는 ../(POSIX 상대 경로 접두사)로 시작하면 Release를 기준으로 디스크에서 직접 읽습니다. 카탈로그 조회도, 레지스트리 호출도 없습니다. 명시적 접두사는 구문 수준에서 로컬 경로 의도와 이름 조회를 구분합니다. aggregate: ./aggregate.yaml을 작성한 Release는 파일을 지정하고, aggregate: checkout은 metadata.name으로 Aggregate를 지정합니다. 해석기는 어느 계층이 적용되는지 결정하기 위해 문자열 내용을 추측하지 않으며, 접두사가 판별 기준입니다. Aggregate 안의 Component type을 포함한 그 밖의 모든 참조는 워크스페이스와 캐시 계층 및 레지스트리 계층을 통해 해석됩니다. 로컬에서 작성한 엔티티는 워크스페이스 루트의 catalog/ 아래나 workspace.catalog_dirs에 나열된 디렉터리에 두며, 상대 파일 경로로 작성된 type은 어떤 카탈로그에도 없는 엔티티로 간주되어 빌드를 중단합니다.
워크스페이스와 캐시. 명시적 로컬 경로 접두사가 없는 참조는 먼저 workspace.catalog_dirs에 나열된 디렉터리(저장소에 작성되거나 벤더링된 프로젝트 로컬 카탈로그 트리 — 구성 형태는 §4 참조)에서, 또는 구성이 workspace.releases 아래에 자체 디렉터리를 지정한 Release의 경우 그 Release의 디렉터리에서 검색됩니다. 그다음 워크스페이스 루트의 catalog/ 디렉터리, 그리고 artifact_cache_dir(이전 레지스트리 해석에서 가져온 아티팩트를 보관하는 gitignore된 .aggrega/cache/ 위치로, 하위 트리는 §4에서 설명합니다)에서 검색됩니다. 두 번째 이후 빌드에서의 캐시 적중 덕분에 프로젝트가 원격 카탈로그 콘텐츠에 의존하더라도 내부 개발 루프는 네트워크 없이 유지됩니다.
레지스트리. 워크스페이스와 캐시 계층에서 일치 항목이 없으면, aggrega pull(또는 --auto-pull이나 워크스페이스의 auto_pull 설정으로 실행된 빌드)은 default_registry(기본값 hub.aggrega.ai)에 대해 ORAS 기반 OCI pull을 수행하고, 이후 빌드를 위해 아티팩트를 캐시에 풀어 놓은 다음 해석된 엔티티로 계속 진행합니다. 둘 다 없는 빌드는 잠금 파일이 고정한 것만 읽으며, 잠금 파일이 없으면 aggrega pull을 안내하며 중단합니다. 레지스트리 호출이 구성하는 OCI URI 형식은 §6(아티팩트 패키징 및 OCI 분류 체계)에서 설명하는 엔티티 타입 분류 체계를 따릅니다. Aggregates와 Manifests의 축약 URI는 레지스트리 호출 전에 완전한 OCI 형식으로 확장되며, 이 확장을 이끄는 추론 규칙은 Manifest의 컨텍스트 인식 축약 URI 참조와 아래 §8에 있습니다.
우선순위와 가림. 해석 우선순위는 엄격하게 로컬 경로 > 워크스페이스와 캐시 > 레지스트리입니다. 레지스트리 엔티티와 같은 식별자를 가진 로컬 카탈로그 디렉터리의 엔티티는 레지스트리 엔티티를 가립니다. 이는 의도된 동작이며, 카탈로그 작성자가 게시 전에 수정 사항을 실험할 수 있게 합니다. 같은 가림이 catalog_dirs와 캐시 사이에도 적용됩니다. 워크스페이스 카탈로그 디렉터리에 있는 엔티티가 캐시된 사본보다 우선하므로, 벤더링된 카탈로그에 대한 로컬 수정이 즉시 반영됩니다.
워크스페이스와 캐시 계층 안에서 catalog_dirs는 순서가 있는 먼저 나온 것이 이기는 우선순위 스택입니다. 같은 엔티티 식별자가 나열된 둘 이상의 카탈로그 디렉터리에 나타나면 먼저 나열된 디렉터리가 이기고 나중 항목은 가려집니다. 즉 재정의되어 로드되지 않으며 오류가 아닙니다. 이를 통해 프로젝트는 자체 카탈로그 디렉터리를 공유 또는 벤더링된 디렉터리 앞에 두고 선택한 엔티티를 식별자로 재정의하며, 나머지는 공유 디렉터리로 넘어가게 할 수 있습니다. 재정의는 관찰할 수 있습니다. 해석 세부 정보가 어느 디렉터리가 이겼고 어느 것이 가려졌는지 보고하므로, 계층화가 조용히 일어나는 일은 없습니다. 가림은 디렉터리 간에만 적용됩니다. 단일 디렉터리 안에서 같은 식별자를 주장하는 두 파일은 작성 실수이며 로드를 중단시킵니다. 두 번 이상 지정된 디렉터리(--catalog 플래그와 catalog_dirs 양쪽에 지정되거나, 목록에 두 번 지정된 경우)는 스택의 한 항목으로, 처음 지정된 위치에서 한 번만 검색됩니다. 따라서 가림은 항상 서로 다른 두 파일 사이에서 일어나며, 디렉터리가 자기 자신과 대조되어 읽히는 일은 없습니다. 우선순위가 작성자가 제어하는 디렉터리 순서를 따르므로 해석된 집합은 결정적입니다.
워크스페이스 루트의 catalog/ 디렉터리는 그 스택의 앞이 아닌 끝에, 디렉터리가 존재할 때만 합류합니다. 따라서 충돌 시 프로젝트가 나열한 어떤 것이든 이를 이기며, 관련 없는 디렉터리 하나를 나열한다고 해서 이것이 조용히 읽히지 않게 되는 일은 없습니다. 나열된 항목이 이미 이 디렉터리에 닿으면 건너뜁니다. 나열된 디렉터리의 탐색은 재귀적이므로 워크스페이스 루트를 지정한 스택은 이미 이를 읽었기 때문입니다. catalog_dirs를 생략하는 것과 빈 목록으로 작성하는 것은 서로 다른 의미입니다. 생략하면 워크스페이스는 여전히 catalog/를 읽고, []로 작성하면 로컬 카탈로그를 전혀 읽지 않습니다. 워크스페이스는 이렇게 로컬 카탈로그가 없음을 선언합니다.
에어갭 빌드. offline: true(§4)를 설정하면 레지스트리 계층을 완전히 건너뜁니다. 로컬 경로 계층 또는 워크스페이스와 캐시 계층에서 해석되지 않은 참조는 조용히 네트워크 호출을 시도하는 대신 엔티티 누락 오류를 표시하므로, 법적으로 네트워크에 접근할 수 없는 CI 파이프라인에 결정적인 빠른 실패 계약을 제공합니다.
단계적 조회가 동작하는 범위. 단계적 조회는 엔티티를 메모리로 가져옵니다. 그 위에 얹힌 추가 해석 메커니즘, 즉 Manifest의 2계층 type 대 name 조회, vocabulary/inheritance-and-interface의 implements 3가지 형식 버전 매칭(정확 / 메이저 호환 범위 / 버전 없음), 프로바이더와 컴포넌트 인스턴스별 축 단위 Recipe 선택은 해석기가 이미 이 단계적 조회를 통해 가져온 엔티티에 대해 동작합니다.
6. 아티팩트 패키징 및 OCI 분류 체계(선두 세그먼트로서의 기능)
Aggrega는 Docker가 컨테이너 이미지를 다루는 것과 같은 방식으로 인프라 로직을 다루며, ORAS(OCI Registry As Storage)를 통해 OCI(Open Container Initiative) 표준을 활용합니다. 사용자는 Aggrega 카탈로그를 모든 표준 레지스트리(GHCR, AWS ECR, Aggrega Hub)에 호스팅할 수 있습니다.
Recipes는 엄격하게 렌더링 기능과 1:1이므로(Recipe는 spec.capability에 하나의 기능을 지정하며 두 개를 대상으로 할 수 없습니다), OCI 레지스트리에서 이를 구성하는 가장 깔끔한 방법은 기능을 저장소의 선두 세그먼트에 두는 것입니다.
OCI 분류 체계는 모든 엔터티 유형을 포괄합니다. 리포지토리 이름은 kind 세그먼트(엔터티의 kind를 소문자로 바꾼 것) 뒤에 엔터티의 식별자가 이어지는 형태이며, 전체가 소문자로 변환됩니다:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, 게시자core, 카테고리datastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, 게시자core, 카테고리computehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, 게시자core(평면 구조, 카테고리 없음)hub.aggrega.ai/aggregate/core/db-module:1.0.0— 재사용 가능한 Aggregate 모듈hub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe, 기능helmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe, 기능helm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe, 기능composehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe, 기능helmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary, 공유 스키마 정의. PascalCasemetadata.name인AIDatastores가 소문자로 변환되어 리포지토리 이름이 됩니다hub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, 공유 Go 템플릿 매핑 조각hub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, 소켓 유형provider(metadata.pluginType세그먼트)
게시 가능한 kind는 카탈로그 작성 kind와 함께, 재사용 가능한 모듈인 Aggregate(나중에 Release의 최상위 spec.aggregate로 참조되든 다른 Aggregate의 aggregates: 블록에 중첩되든 게시 가능), 그리고 컴파일러가 라우팅하고 런타임이 실행하는 WebAssembly 아티팩트에 대한 콘텐츠 주소 참조인 Plugin을 포함합니다. Plugin은 카탈로그 작성 kind가 아니라 구조적인 게시 가능 아티팩트입니다. Release와 Manifest는 소스 관리에 존재하며 절대 푸시되지 않는 배포 측 입력이므로(aggrega push가 이를 거부합니다) 게시 미디어 타입이 없습니다. aggrega push --list-kinds는 설치된 바이너리가 게시하는 집합을 한 줄에 하나의 kind씩 보고합니다. 각 게시 가능 kind는 게시물이 취하는 두 가지 형태 각각에 대해 고유한 OCI 미디어 타입을 가집니다:
| 엔터티 kind | 문서로 게시 | 선언한 파일과 함께 게시 |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — 파일을 선언하지 않음 |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — 파일을 선언하지 않음 |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — 파일을 선언하지 않음 |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — 파일을 선언하지 않음 |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — 파일을 선언하지 않음 |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — 자체 manifest를 통해 게시 |
게시물이 담는 내용, 그리고 그에 따른 형태는 엔터티가 선언하는 것에서 결정됩니다. kind나 디렉터리에 있는 것에서 결정되지 않습니다. 게시물은 엔터티 문서와 엔터티 자신이 그 옆에 명시한 파일을 담습니다. 즉 Recipe나 FeatureRecipe의 로컬 source:(디렉터리는 그 entity.lock에 기록된 무시 규칙이 유지하는 그 아래의 모든 파일과 함께 이동합니다), valuesMapping:, workload:, artifacts: 항목이 $import:로 가져오는 각 파일, 고정 단계가 작성한 entity.lock, 그리고 Component나 Feature가 가져오는 각 스키마 파일(가져오기 체인의 모든 파일 포함)입니다. 디렉터리의 다른 것은 이동하지 않습니다. 엔터티 옆의 메모, README, 빌드 출력은 이름이 무엇이든 게시 대상에 속하지 않으며 게시 형태를 바꾸지 않습니다. 아무것도 명시하지 않은 엔터티는 작성된 문서 그대로 바이트 단위로 해당 kind의 +yaml 미디어 타입으로 게시됩니다. 파일을 명시한 엔터티는 문서와 그 파일들의 gzip tar로 해당 kind의 +tar+gz 미디어 타입으로 게시됩니다. Aggregate, Plugin, 라이브러리 kind는 문서 옆에 파일을 선언하지 않으므로 항상 문서로 게시됩니다. 워크스페이스 루트의 Aggregate도 마찬가지인데, 선언하는 모든 경로가 담고 있는 파일이 아니라 다른 엔터티를 가리키기 때문입니다. 내용이 모두 인라인인 Recipe도 그렇습니다. 원격 소스는 파일이 아니라 참조이므로 아무것도 담지 않지만, 그 고정을 기록한 entity.lock 때문에 그런 Recipe는 아카이브가 됩니다. 각 미디어 타입의 버전 세그먼트는 모든 게시 가능 kind에 공통이며, 인코딩 세그먼트는 바이트가 두 형태 중 어느 것인지를 나타냅니다. 다운스트림 도구는 전체 미디어 타입 문자열(kind, 버전, 인코딩 모두)로 분기합니다.
작성 형태 중 하나는 게시물이 알 수 있는 디렉터리를 명시하지 않습니다. 바로 템플릿으로 작성된 로컬 소스입니다. 그 디렉터리는 Release가 템플릿을 채운 뒤에야 정해지므로, 엔터티는 기록된 무시 규칙이 유지하는 자신의 디렉터리 안 모든 파일을 담아 Release가 어느 디렉터리를 고르든 이미 이동해 있도록 합니다. 이런 경우 aggrega push가 이를 알립니다. 명시된 것만 담는 데에는 비용이 있으며, 그 비용은 소비자가 집니다. 엔터티가 읽지만 어디에도 명시하지 않은 파일은 이동하지 않으며, 그 부재를 마주하는 것은 게시자의 푸시가 아니라 소비자의 빌드로, 캐시 슬롯 안에서 누락된 경로를 지목합니다.
소스 디렉터리의 어떤 파일이 엔터티에 속하는지는 엔터티가 고정될 때 한 번 결정되고 기록됩니다. 작성자 워크스페이스에서 엔터티의 기능을 제공하는 플러그인이 그 생태계가 결코 배포하지 않는 것을 선언하고(차트 플러그인의 버전 관리 디렉터리와 차트의 .helmignore 준수, 모듈 플러그인의 .terraform/ 등), 엔터티 옆에 있는 작성자의 .aggregaignore가 최종 결정권을 가집니다. 고정 단계는 그 플러그인과 조합된 규칙을 entity.lock에 기록하며, 게시, 소스 고정의 모든 비교, 엔터티의 lockfile 행, 렌더링은 모두 플러그인에 다시 묻지 않고 기록된 규칙을 적용합니다. 따라서 게시되는 것은 작성자 자신의 빌드가 렌더링하는 것과 같으며, 바인딩이 바뀌거나 바이너리가 새로워져도 엔터티를 다시 고정하기 전까지 다이제스트는 바뀌지 않습니다. 컴파일러는 어떤 생태계에 대해서도 의견을 갖지 않습니다. 규칙은 플러그인과 작성자에게서 오며 컴파일러는 이를 대조할 뿐입니다. 엔터티 파일 중 심볼릭 링크는 따라가지 않고 거부되는데, 가리키는 대상이 그 이름으로 이동하게 되기 때문입니다. aggrega pin에서 규칙 전체를 설명합니다.
Recipe의 이름에는 도메인 접두사도 기능도 포함되지 않습니다. 엔터티 유형 디렉터리와 기능 세그먼트가 이미 둘 다 나타내기 때문입니다.
명명 관례: Components(도메인 2)는 {publisher}/{category}/{name}을 사용하고, Features(도메인 2)와 재사용 가능한 Aggregates(도메인 1)는 {publisher}/{name}을 사용하며, 게시자 세그먼트는 벤더/작성자를 나타냅니다(core = 공식 표준 라이브러리, acme = 기업). 도메인 3 엔터티(Recipe, FeatureRecipe)는 {capability}/{name}을 사용하며, 여기서 기능은 엔터티가 spec.capability에 선언한 provider입니다. 참조는 엔터티를 리프만으로 이름 붙일 수도 있습니다. Recipe 이름에는 기능도 포함되지 않는데, 이미 정규 URI의 선두 세그먼트이기 때문입니다.
Recipes는 implements 키워드를 사용해 자신이 충족하는 인터페이스에 바인딩합니다. implements 필드는 정확한 일치, 메이저 호환 범위, 버전 없는 일치를 지원합니다(implements 버전 일치는 vocabulary/inheritance-and-interface 참조). Manifest 매핑 항목의 Recipe는 매핑 대상 타입 또는 그 타입이 extends하는 기반을 구현해야 합니다. 즉 항목의 키, 그리고 키가 버전을 지정하지 않고 도달하는 각 컴포넌트 인스턴스의 타입(빌드가 그 인스턴스를 컴파일하는 버전 기준)입니다. 따라서 키가 인스턴스를 그 타입의 다른 버전용으로 작성된 Recipe로 보낼 수는 없습니다.
Ops 엔지니어가 aggrega push를 실행하면 CLI는 엔터티를 그 형태로 해당 버전에 불변으로 게시합니다. 소비자는 3계층 해석 모델을 통해 이를 가져와 로컬 .aggrega/cache/에 캐시하고, 담긴 내용(아카이브의 파일들 또는 문서만)을 엔터티의 캐시 슬롯(§4)에 배치합니다.
pull한 엔터티는 자신이 담고 있는 파일을 카탈로그 디렉터리에서 옆에 있는 파일을 읽을 때와 똑같이 읽습니다. 엔터티는 배치된 트리 안의 자기 위치에서 읽히므로, 엔터티가 선언하는 상대 경로 source: 또는 $import:는 직접 작성한 것이든 템플릿이 생성한 것이든 게시된 내용 안에서 해석되며, 엔터티 자신의 디렉터리를 벗어나는 경로는 카탈로그 디렉터리에서와 마찬가지로 거부됩니다. 트리 바깥의 어떤 것도 그 대신 읽히지 않습니다. 빌드가 실행되는 디렉터리도, 캐시 슬롯에 심어 둔 파일도 읽히지 않습니다. 스키마를 파일에서 가져오는 Component 또는 Feature는 그 파일을 함께 담으므로, pull한 사본은 게시된 계약을 로드하고 그 계약에 맞춰 작성된 값을 카탈로그 디렉터리에서 읽은 사본과 똑같이 검증합니다.
패키지에서 엔터티를 다시 읽어 내는 것은 그 역방향 단계이며, 이 단계는 문서의 이름이 아니라 문서가 무엇인지로 엔터티를 식별합니다. 즉 패키지 최상위에 있으면서 kind:가 게시 가능한 엔터티 kind인 문서입니다. 엔터티 파일의 이름은 카탈로그 관례이지 계약이 아니므로, recipe.yaml은 형식이 요구하는 것이 아니라 표준 라이브러리 카탈로그가 쓰는 이름이며, 엔터티 옆에 함께 담긴 파일(차트 템플릿, compose 조각 등)이 엔터티로 오인되지 않습니다. 이 규칙은 반대로, 즉 소비자가 찾는 kind를 기준으로 할 수 없습니다. kind는 패키지 안에 있는 엔터티로부터 읽히므로, 패키지를 열어야 하는 시점에는 기준으로 삼을 kind가 없기 때문입니다. 패키지 최상위에 엔터티 문서가 두 개 있으면 읽는 쪽은 하나를 고르지 않고 중단합니다. 이는 다른 클라이언트가 엔터티 두 개가 있는 디렉터리 전체를 묶어 만든 패키지로, 그렇게 되면 각 엔터티의 게시 좌표 아래에 하나의 아티팩트로 놓이게 됩니다. 이 제품의 게시는 그런 패키지를 만들 수 없습니다. 각 엔터티는 자신이 선언한 것만 담기 때문이며, 게시하는 쪽도 그런 디렉터리를 거부합니다. Aggregate, Release, Manifest를 제외한 모든 kind는 자신만의 디렉터리를 가지며, aggrega pin과 aggrega push는 그 밖의 kind의 엔터티 옆에 다른 엔터티가 있으면 거부하고, 카탈로그 로드, lint, 빌드는 디렉터리를 그대로 둡니다. 디렉터리의 이름은 어느 쪽에서도 판단하지 않습니다. <name>/<version>/ 레이아웃은 표준 라이브러리 카탈로그의 관례입니다.
게시된 엔터티도 같은 단계를 거쳐 읽힙니다. 좌표는 엔터티의 사본을 정확히 하나, 선언이 정한 형태로 담으며, 사람은 그 옆에 게시된 읽기용 사본이 아니라 aggrega inspect oci://<registry>/<repository>:<tag>로 그것을 살펴봅니다. 따라서 빌드가 해석하는 사본과 어긋날 수 있는 두 번째 사본은 없습니다. 이 명령은 위의 규칙에 따라 아카이브를 풀고, Plugin의 엔터티는 함께 게시된 실행 파일이 아니라 manifest에서 읽으며, 그 결과를 해당 kind의 파일이 렌더링되는 방식대로 렌더링합니다. 게시된 엔터티 읽기를 참조하십시오.
검색 가능한 manifest 어노테이션. 모든 게시는 아티팩트의 OCI manifest에 검색 가능한 소수의 어노테이션을 찍어, 레지스트리 인덱스나 카탈로그 브라우저가 각 엔터티 본문을 가져와 파싱하지 않고도 카탈로그 메타데이터로 아티팩트를 필터링할 수 있게 합니다. 모든 엔터티는 사람이 읽을 수 있는 설명(표준 OCI description 어노테이션)과 카탈로그 카테고리 및 kind를 담습니다. Plugin은 여기에 더해 소켓 유형과 자신이 제공하는 capability를 담습니다. 이 어노테이션들은 aggrega registry update가 로컬 검색 인덱스(§8)로 다시 읽어 들이는 내용입니다.
게시되는 모든 파일에는 이름이 붙습니다. 게시물이 담는 각 파일은 manifest에서 표준 org.opencontainers.image.title 어노테이션으로 이름이 붙으며, 이는 일반 OCI 클라이언트가 아티팩트를 디렉터리로 pull할 때 그 파일을 기록하는 이름입니다. 이름은 파일이 무엇인지를 나타내며, 확장자는 파일의 미디어 타입을 따릅니다.
| 게시되는 것 | 일반 OCI 클라이언트가 기록하는 파일 |
|---|---|
| 문서로 게시된 엔터티 | entity.yaml |
| 선언한 파일과 함께 게시된 엔터티 | entity.tar.gz |
| Plugin | 엔터티인 entity.yaml과 그 옆의 실행 파일 entity.wasm |
| 아티팩트에 첨부된 서명 | signature.json |
| 아티팩트에 첨부된 지원 중단 표시 | deprecation.json |
aggrega push-artifact로 게시된 데이터 아티팩트 | --name으로 지정한 이름 |
따라서 oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server는 게시된 엔터티를 게시된 그대로 바이트 단위로 ./server/entity.yaml에 남깁니다. oras는 이름이 없는 디스크립터를 건너뛰고도 성공을 보고하므로, 게시물이 묶는 모든 디스크립터에는 이름이 붙습니다. 이름은 게시된 파일의 이름이 아니라 미디어 타입만으로 도출되므로, 이름이 다른 파일에서 같은 바이트를 게시해도 같은 manifest가 만들어집니다. 파일과 함께 게시된 엔터티는 패키지로 도착합니다. entity.tar.gz가 패키지의 이름이며, 그 안의 엔터티는 파일 이름이 아니라 위의 규칙으로 찾습니다. Aggrega 자체의 해석은 이 이름들을 전혀 읽지 않습니다. 각 파일을 미디어 타입으로 선택하고 다이제스트로 신뢰하므로, 이 이름들은 다른 모든 클라이언트를 위한 것입니다.
7. Recipe 아키텍처: 포인터와 매퍼
Recipe 작성 기능 전체는 entities/recipe를 참조하십시오. source:(포인터), valuesMapping:(매퍼, 세 가지 작성 방식: 인라인 블록 스칼라, 파일 $import:, MappingLibrary 항목을 가리키는 라이브러리 $import:), Wasm 기반 소스 스키마, 네이티브 IaC 지원, 그리고 작동 예제를 다룹니다.
8. 기본 레지스트리와 컨텍스트 인식 축약 URI
YAML이 비대해지는 것을 없애기 위해, 컴파일러는 축약 URI를 그것이 나타나는 스키마 위치에 맞춰 컨텍스트를 인식하여 해석합니다. 기본 레지스트리는 .aggrega-config.yaml에서 구성합니다(기본값은 hub.aggrega.ai).
레지스트리 호스트는 한 가지로만 읽힙니다. 각 registries[].host는 호스트 자체로 작성합니다. 즉 점을 포함하는 소문자 호스트 이름, localhost, 포트가 뒤따르는 단일 이름, IPv4 주소, 또는 대괄호로 묶은 IPv6 주소이며, 각각 선택적으로 :port를 붙일 수 있고 스킴, 경로, 자격 증명, 대문자는 포함하지 않습니다. 그 표기가 레지스트리별 신뢰 정책을 찾는 키이고, 공식 허브에 내장된 서명 요구 사항이 hub.aggrega.ai를 키로 하기 때문입니다. default_registry도 같은 방식으로 호스트를 지정하며, 그 뒤에 ghcr.io/acme처럼 리포지토리 경로를 붙일 수 있습니다. 그러면 기본값을 통해 게시되는 모든 것이 그 경로 아래에 놓이고 모든 짧은 참조가 그 아래에서 해석되지만, 신뢰는 여전히 호스트만으로 결정됩니다. default_registry는 대신 registries 항목의 name:으로 작성할 수도 있으며, 이 경우 그 항목의 호스트를 나타냅니다. 이 이름은 구성이 해석될 때 모든 구성 파일과 환경을 적용한 뒤 유효한 항목들을 기준으로 한 번 읽히므로, 기본값을 읽는 모든 곳(게시, 위치 바인딩, 서명 검증, 모든 신뢰 조회)이 그 한 항목의 호스트를 읽으며, 어느 것도 그 이름과 같은 철자의 호스트에 도달하지 않습니다. 이름 뒤에 경로가 붙으면 거부됩니다. 이름은 위치가 아니라 항목을 나타내기 때문입니다. 이름은 호스트 표기보다 먼저 일치 여부를 확인하며, 두 항목이 같은 이름을 가지면 모호하다는 이유로 거부됩니다. 같은 해석이 pull이 호스트로 하는 세 가지를 결정합니다. 호스트가 없는 카탈로그 식별자가 바인딩되는 레지스트리 위치, 가져온 아티팩트가 서명을 검사하는 레지스트리를 가리키는지 여부, 그리고 그 검사가 어떤 신뢰 정책을 기준으로 실행되는지입니다. 레지스트리에 도달하면서도 그 정책을 놓칠 수 있는 표기(대문자, 명시적인 기본 HTTPS 포트, 스킴, 자격 증명, registries 항목의 호스트에 붙은 경로)는 구성된 곳에서 작성해야 할 표기를 알려 주며 거부되고, 포트가 없고 어떤 항목도 가리키지 않는 단일 이름도 마찬가지입니다. 이는 호스트가 아니라 카탈로그 식별자의 첫 세그먼트 형태이기 때문입니다. 이 거부는 값을 설정할 수 있는 모든 계층에 적용됩니다. 스키마가 각 registries[].host에 같은 형태를 패턴으로 명시하는 구성 파일, AGGREGA_DEFAULT_REGISTRY 환경 변수, 그리고 명령줄입니다. 따라서 구성이 지정할 수 있는 모든 호스트는 그 호스트를 위해 작성된 정책에 따라 아티팩트가 검증되는 호스트입니다. 호스트는 표기만으로 판단합니다. 이름이 해석되는지, 그곳에서 레지스트리가 응답하는지는 컴파일러가 가져오지 않는 런타임 상태입니다. 허용되는 형식과 예제는 configuration에 자세히 설명되어 있습니다.
축약 URI는 Manifest를 기준으로 컨텍스트를 인식하여 해석됩니다. 구체적인 추론 규칙은 ../language-reference/entities/manifest.md §Context-Aware Shorthand URIs를 참조하십시오.
레지스트리 관리
aggrega registry는 워크스페이스가 아는 레지스트리와 그 서명 신뢰 정책을 관리합니다. 레지스트리의 식별자는 호스트이며, 하위 명령들은 하나의 지정 모델을 공유합니다.
aggrega registry add <host>는 레지스트리를 등록하고 신뢰 정책을 고정하며, 신뢰 플래그로 정책을 직접 지정하지 않으면 처음 연결할 때 레지스트리가 공지하는 정책을 가져옵니다. 선택적인--name <alias>는 같은 호스트 키 항목에 친숙한 별칭을 붙입니다. 호스트가 여전히 식별자이며, 별칭은 레지스트리를 지정하는 모든 곳에서 그 호스트로 해석됩니다. 별칭은 레지스트리 전체에서 고유합니다.aggrega registry list는 구성된 모든 레지스트리를 호스트, 별칭, 간단한 신뢰 상태 요약, 기본값 표시와 함께 호스트 오름차순으로 출력합니다. 해석된 구성을 읽으며 네트워크에 연결하지 않습니다.aggrega registry remove <name|host>는 호스트나 별칭으로 지정한 레지스트리의 신뢰 정책 항목을 삭제합니다. 신뢰 정책만 제거합니다.default_registry포인터는 그대로 두며 그 호스트로 push하는 기능도 영향을 받지 않으므로, 호스트는 도달할 수 없게 되는 것이 아니라 기본 신뢰로 돌아갑니다. 제거된 항목의 이름으로 작성된default_registry는 이후 아무것도 가리키지 않으며, 다시 작성할 때까지 거부됩니다.aggrega registry update는 아래에 설명하는 로컬 검색 인덱스를 갱신합니다.
레지스트리를 지정하는 모든 곳(registry 하위 명령 인수, 또는 aggrega push와 aggrega push-artifact의 --registry 플래그)에서 같은 해석기가 토큰을 해석합니다. 구성된 별칭은 해당 호스트로 해석되고, 그 밖의 토큰은 그것이 가리키는 호스트로 읽히며 참조의 스킴, 경로, 자격 증명은 제거됩니다. 그 호스트가 서명 결정의 기준이 되는 곳(aggrega push 또는 aggrega push-artifact의 대상, 또는 aggrega registry add가 항목을 기록하는 키)에서는 위의 한 가지 해석이 적용되며, 그렇게 작성되지 않으면 작성해야 할 표기를 알려 주며 거부됩니다. 그렇게 작성된 미등록 호스트는 정당한 대상이며 허용됩니다.
로컬 검색 인덱스
aggrega registry update [<name|host>]는 워크스페이스가 아는 레지스트리의 로컬 검색 인덱스를 만듭니다. 구성된 각 레지스트리의 리포지토리를 순회하여 각각의 가장 높은 릴리스 버전을 선택하고, 그 버전의 검색 가능한 manifest 어노테이션(§6)을 읽어, 레지스트리별 인덱스를 아티팩트 캐시에 기록합니다. 인수가 없으면 구성된 모든 레지스트리를 인덱싱하고, 레지스트리 인수(호스트 또는 별칭)를 하나 주면 그 레지스트리만 인덱싱합니다.
이 인덱스는 패키지 관리자에서 익숙한 명시적 갱신 모델을 따릅니다. registry update가 레지스트리에 연결하는 명령이며, 이후의 aggrega search는 기록된 인덱스를 오프라인으로 읽습니다. 레지스트리의 레코드 파일은 결정적입니다. 같은 레지스트리 상태에 대해 두 번 갱신하면 바이트 단위로 동일한 결과가 나오며, 최신성 타임스탬프는 옆의 별도 파일에 있으므로 레코드에 영향을 주지 않습니다. 릴리스 버전이 없거나 읽을 수 없는 리포지토리는 건너뛰므로, 읽을 수 없는 리포지토리 하나 때문에 인덱스 전체를 포기하는 일은 없습니다.
게시된 카탈로그 스냅샷
표준 라이브러리 카탈로그를 게시할 때마다 카탈로그 전체도 함께 게시됩니다. 이는 하나의 OCI 아티팩트로, 해당 게시가 게시한 커밋 시점에 카탈로그 트리가 보유한 모든 파일을 gzip으로 압축한 tar이며, 카탈로그가 게시되는 레지스트리 아래의 catalog/snapshot에 위치합니다. 공식 허브의 경우 hub.aggrega.ai/catalog/snapshot입니다. 이는 해당 게시의 모든 엔터티가 레지스트리에 올라간 후에만 푸시되므로, 레지스트리에 없는 엔터티를 가리키지 않습니다. 빌드 원본인 커밋과 latest로 태그가 지정되며, 게시의 모든 엔터티와 마찬가지로 게시자가 키리스 방식으로 서명하므로, 게시자의 ID로 레지스트리의 신뢰 정책에 따라 검증됩니다. latest는 스냅샷이 서명된 후에만 그 스냅샷으로 이동합니다. 아카이브는 하나의 고정된 레이아웃으로 작성되므로(항목은 이름의 오름차순이며, 각 항목은 같은 모드, 소유자, 수정 시간을 가짐), 하나의 커밋은 항상 같은 tar를 만듭니다.
이를 읽는 유일한 주체는 워크스페이스가 카탈로그 폴더를 지정하지 않은 가져오기입니다. 즉 workspace.catalog_dirs도, AGGREGA_CATALOG_DIRS도 없고, 워크스페이스 루트에 catalog/ 디렉터리도 없는 경우입니다. aggrega import, 편집기 세션의 가져오기, 어시스턴트의 가져오기 도구는 같은 작업을 실행하므로 모두 같은 방식으로 스냅샷을 얻습니다. 가져오기는 pull과 같은 송신 트래픽 게이트와 로그인을 거쳐 워크스페이스의 기본 레지스트리에서 스냅샷을 가져오고, 무엇이든 보관하기 전에 해당 레지스트리의 신뢰 정책에 따라 서명을 검증한 뒤, 워크스페이스의 아티팩트 캐시에 보관하고, 그 다이제스트에 고정된 채로 거기서 카탈로그 폴더로 읽습니다. 따라서 임포터에는 카탈로그의 Components가 제공되고, --target은 그 Recipes로부터 Manifest 초안을 작성하며, 이는 카탈로그 폴더가 거치는 경로와 정확히 같습니다. 가져오기가 초안 옆에 쓰는 기록은 매니페스트 다이제스트로 스냅샷을 가리키므로, 같은 초안을 나중에 가져올 때는 요청 없이 같은 카탈로그를 읽으며, aggrega import --upgrade는 최신 스냅샷을 가져와 그때부터 그것을 기준으로 가져옵니다. 오프라인 설정에서는 스냅샷을 가져와야 하는 가져오기가 실행할 것을 알려 주며 중단됩니다. 카탈로그 폴더를 지정한 워크스페이스는 그것을 기준으로 가져오며 스냅샷을 가져오지 않습니다. 다른 어떤 명령도 스냅샷을 읽지 않습니다. pull, 빌드, 검증은 §5의 계층을 통해 각 엔터티를 해석하고 잠금 파일에 고정하며, 가져오기의 초안은 카탈로그 엔터티를 이름으로 참조하므로, 이를 빌드할 때도 같은 방식으로 해당 엔터티가 해석됩니다.
9. 잠금 파일 고정과 아티팩트 불변성
잠금 파일 고정 원칙은 모든 의존성을 특정 콘텐츠 주소 지정 아티팩트에 고정합니다. 첫 잠금 파일 해석(aggrega pull) 시 리졸버는 레지스트리를 조회하고, URI의 세 가지 형태 제약(정확한 버전 / 범위 / 버전 없음)에 따라 버전을 선택한 뒤, 고정된 버전과 다이제스트를 Release의 <release-stem>.lock에 기록합니다. 이후의 aggrega build 호출은 레지스트리의 변경 여부와 관계없이 고정된 값을 사용하며, 새 버전이 게시되어도 기존 잠금 파일에는 영향을 주지 않습니다.
고정 모델에는 핵심이 되는 규칙이 하나 있습니다. 어떤 name:version이 레지스트리에 게시되어 다이제스트 D로 해석되면, 그 매핑은 영구적입니다. 같은 name:version을 다른 내용으로 다시 게시하면 푸시 시점에 거부됩니다. aggrega push 자체가 모든 게시에서 이를 강제합니다. 대상 레지스트리에서 name:version의 기존 아티팩트를 해석하여, 존재하고 다이제스트가 푸시하려는 내용과 일치하면 아무것도 업로드하지 않고 해당 게시에 아직 없는 것만 첨부합니다. 즉 게시 날짜와, 푸시가 서명하는 경우 서명입니다. 존재하지만 다이제스트가 다르면 두 다이제스트를 모두 명시한 불변성 위반 오류와 함께 푸시가 중단됩니다.
불변성이 중요한 이유는 두 가지 결과 때문입니다.
- 잠금 파일 고정은 신뢰할 수 있습니다. 잠금 파일이 다이제스트
D의mariadb:1.0.0을 기록하면, 다이제스트로 가져오는 빌드는D의 바이트를 받습니다. 불변성이 없다면 레지스트리 측의 변경이 잠금 파일 고정 아래에서D의 바이트를 바꿔치기하여 잠금 시점부터 빌드 시점까지의 안정성을 무너뜨릴 수 있습니다. 재현 가능한 빌드는 이 보장에 기반합니다. - 게시 후 메타데이터 변경에는 명확한 경로가 있습니다. 게시된 버전을 사용 중단으로 표시하거나, 서명 키를 교체하거나, 증명을 수정하는 작업은 게시된 아티팩트를 변경하는 방식으로는 할 수 없습니다(규칙이 이를 금지합니다). 새 패치 버전을 게시하거나, 메타데이터 변경을 별도로 기록하는 사이드카 아티팩트를 게시해야 합니다. 두 경로 모두 감사가 가능하며(새 버전이나 사이드카는 별개의 레지스트리 항목으로 나타납니다), 어느 쪽도 원본 아티팩트의 바이트를 바꾸지 않습니다.
불변성 규칙은 OCI로 게시되는 모든 Aggrega 아티팩트(엔터티, SchemaLibrary, MappingLibrary, 그리고 Recipe pipeline[].plugin: / FeatureRecipe pipeline[].plugin: / 워크스페이스 구성 plugins.{governance,linter,importer}[]:에서 참조하는 Wasm 플러그인)에 똑같이 적용됩니다. 잠금 파일에서 name:version과 콘텐츠 다이제스트로 고정된 모든 것은 불변성의 대상입니다.
불변성은 무조건적이며, 어떤 구성으로도 완화되지 않습니다. 덮어쓰기를 허용하는 플래그나 워크스페이스 구성 설정은 없습니다. 레지스트리가 운영자가 선택할 수 있는 덮어쓰기 경로를 제공하지 않기 때문입니다. 변경된 내용은 새 버전으로 게시되며, aggrega lint --pre-publish는 버전 증가가 변경의 분류와 일치하는지 검증합니다.
더 새로운 버전으로 다시 해석하려면 사용자가 명시적으로 조치해야 합니다. aggrega pull --upgrade --release <release> <uri>는 다른 모든 고정을 유지한 채 단일 의존성을 다시 해석하고, aggrega pull --upgrade --release <release>는 모든 의존성을 현재 레지스트리 상태에 대해 다시 해석합니다. 범위 형태와 버전 없는 형태의 의존성은 일치하는 최신 버전으로 다시 해석되며, 정확한 버전 형태의 고정은 사용자가 다른 정확한 버전으로 명시적으로 업그레이드하지 않는 한 바뀌지 않습니다. 잠금 파일은 빌드의 기준 정보이며, 사용자가 입력한 형태는 작성 시점의 버전 제약을 표현합니다.
10. 카탈로그 엔터티 이름 형태 검사
카탈로그 엔터티 이름은 엔터티 종류별 패턴을 따릅니다. 패턴은 아래에 열거되어 있으며, 종류별 세부 사항은 엔터티 레퍼런스 개요에 있습니다. 이 이름은 개발자가 Aggregate나 Release에 작성하는 인스턴스 이름과는 다른 영역입니다. 인스턴스 이름은 종류와 관계없이 하나의 패턴을 공유하며, 그 패턴은 ../language-reference/02-naming-conventions.md의 “Instance Names”에 있습니다. 카탈로그 YAML이 선언하는 metadata.name 필드가 엔터티의 정식 참조 URI와 항상 같지는 않습니다. Component와 Feature는 게시자 세그먼트와 그룹 세그먼트를 metadata.name에 직접 포함합니다. Recipe와 FeatureRecipe는 리프만으로 된 metadata.name을 선언하며, 정식 두 세그먼트 URI는 그 리프를 엔터티가 선언한 spec.capability와 짝짓습니다. 모든 라이브러리 종류는 metadata.name에 PascalCase 토큰을 선언합니다.
엔터티 종류별 형태:
- Component —
metadata.name에 선언된 세 개의 kebab-case 세그먼트{publisher}/{category}/{name}. 예:core/datastore/postgres. - Feature —
metadata.name에 선언된 두 개의 kebab-case 세그먼트{publisher}/{name}. 예:core/data-masking. - Recipe —
metadata.name에 있는 단일 kebab-case 리프(예:postgres). 정식 참조 URI{capability}/{name}(위 §6 참조)은 엔터티가 선언한spec.capability를 그 리프와 짝짓습니다. 선행 세그먼트는 디스크상의 엔터티 위치가 아니라spec.capability와 대조되므로,recipe.yaml을 옮겨도 참조 방식은 바뀌지 않습니다. 표준 라이브러리 카탈로그는 트리가 좌표를 반영하도록 엔터티를<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yaml에 두지만, 이 반영은 URI의 출처가 아니라 카탈로그 관례입니다. 참조는 recipe를 단독으로, 즉 capability 세그먼트 없이 리프만으로 지정할 수도 있습니다. 이는 실제로 가장 많이 쓰이는 형태이며, 카탈로그에서 그 이름을 가진 recipe가 하나뿐이면 언제든 해석됩니다. Recipe URI에는 게시자 세그먼트가 없으며, 세 번째 세그먼트를 가진 참조는 어떤 recipe와도 일치하지 않습니다. - FeatureRecipe —
metadata.name에 있는 단일 kebab-case 리프(예:k8s-secret-from-parameter)로, Recipe와 대칭입니다. 정식 URI{capability}/{name}은 선언된spec.capability와 리프로 구성되고, 단독 리프도 같은 방식으로 허용되며,<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yaml트리는 관례에 따라 좌표를 반영합니다. - 라이브러리 종류 — SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary —
metadata.name에^[A-Z][A-Za-z0-9]*$와 일치하는 PascalCase 단일 토큰(예:BaseComponents,AIDatastores,BaseWorkloads). 형태는 모든 라이브러리 종류에서 같으므로, 라이브러리 간에 항목을 옮겨도 다른 관례에 맞춰 이름을 바꿀 필요가 없습니다. 각 라이브러리 종류의 JSON Schema 엔벨로프도 아래에 설명된 검사와 별도로 이 패턴을 선언합니다.
Component, Feature, Recipe, FeatureRecipe의 경우 metadata.name에 대한 JSON Schema는 비어 있지 않은 모든 문자열을 허용하므로, 이 종류들에서는 형태에 관한 어떤 것도 구조적이지 않습니다. 문서화된 모든 형태는 — 엔벨로프가 패턴을 함께 선언하는 라이브러리 종류를 포함하여 — 게시 규율 플러그인이 검사하며, 이 플러그인은 컴파일러 배포판과 공유하는 정규식 단일 출처로 패턴을 보유합니다. 여기서 형태를 부여하고 플러그인이 무시하는 종류는 없습니다.
이 검사는 선택 사항입니다. 하나의 명령이 이를 수행하며, 작성자가 요청할 때만 실행됩니다. 이를 수행한다고 흔히 여겨지는 두 명령은 수행하지 않습니다:
aggrega lint는 이름 형태 위반을 보고합니다. 플러그인은 각 엔터티의metadata.name을 해당 종류의 패턴과 비교합니다. 검사는 작성자가aggrega lint를 호출할 때 실행됩니다. 단일 엔터티에 대해,--release로 Release의 의존성 클로저에 대해, 또는 인수 없이 호출하면 모든 카탈로그 엔터티에 대해 실행되며, CLI가 노출하는 에디터용 도구 영역에서도 같은 규칙 집합에 접근할 수 있습니다. 결과는 권고 사항입니다.warn심각도로 보고되며 중단하지 않습니다.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)결과는 심각도와 해당 규칙이 등록된 짧은 코드로 시작하며, 이 코드는 aggrega explain E0278로 자세히 볼 수 있습니다. 문제가 된 파일의 경로가 결과 위에 출력되며, 카탈로그 전체 실행은 검사한 엔터티 수와 발생한 권고 결과 수로 끝납니다.
aggrega build는 이름 형태를 검사하지 않습니다. 렌더링된 출력은 Aggrega 엔터티 이름에 의존하지 않으므로, 규격에 맞지 않는 이름을 가진 카탈로그에 대한 빌드는 경고나 진단을 내보내지 않고 평소와 똑같이 성공합니다.aggrega push도 이름 형태를 검사하지 않습니다. 게시는 다른 이유로 거부됩니다. 가장 대표적인 것은 위의 불변성 규칙으로, 기존name:version을 다른 내용으로 다시 게시하면 중단됩니다. 거부 메시지가aggrega lint --pre-publish를 언급하는 경우, 이는 작성자에게 실행할 명령을 알려 주는 것이며 push가 그것을 실행하지는 않습니다.
빌드도 게시도 형태를 검사하지 않으므로, 관례가 지켜지기를 원하는 카탈로그는 pre-commit 훅이나 파이프라인 단계에서 aggrega lint를 의도적으로 실행합니다. 이름 형태 결과는 권고 사항이라는 점에 유의하십시오. aggrega lint는 이를 보고하고도 성공적으로 종료하므로, 관례를 기준으로 통과 여부를 가르려는 파이프라인은 종료 상태에 의존하지 말고 보고된 결과를 읽어야 합니다.
워크스페이스별 정책으로 이 규칙을 억제할 수 있습니다:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default false정책이 설정되면 이름 형태 규칙은 아무것도 보고하지 않습니다. 단일 호출에 대해 aggrega lint --allow-nonstandard-names로 설정하거나, --no-allow-nonstandard-names로 다시 강제로 끌 수도 있습니다. 정당한 용도로는 게시되지 않을 카탈로그, 다중 게시자 실험, 특수 목적 엔터티가 있습니다.
11. 어노테이션 기반 Feature 확장
Manifest의 mappings.features.annotations 블록은 어노테이션 키와 Feature 유형 간의 바인딩, 그리고 각 어노테이션이 채울 수 있는 Feature 스키마 속성을 지정하는 필러별로 묶인 라우팅 테이블(maps.infra, maps.values)을 선언합니다. 해석 단계의 어노테이션 확장 하위 단계는 Release 경계를 바깥에서 안쪽으로, Aggregate 하위 시스템을 바깥에서 안쪽으로 순회하면서, 전체 값 단위 및 하위 키 단위의 null 옵트아웃을 포함한 캐스케이드와 재정의를 통해 컴포넌트별 유효 어노테이션 집합을 계산하고, IR 출처 정보에 origin: annotation을 담은 합성 Feature 연결을 주입합니다. 바인딩 형태와 작성 방법에 대한 전체 설명은 language-reference/entities/manifest.md와 language-reference/providers/well-known-annotations.md에 있으며, 이 절에서는 확장 경로가 의존하는 카탈로그 로드 시점과 inspect 시점의 동작 방식을 설명합니다.
스키마 컴파일 캐시. 각 Feature의 spec.schema.{infra,values}는 빌드당 한 번 컴파일되고 캐스케이드 순회 전반에서 재사용됩니다. 동일한 Feature 스키마에 대한 반복적인 하위 키 단위 유형 검증(컴포넌트마다 하나의 캐스케이드 범위, 컴포넌트는 수백 개)은 다시 컴파일하지 않고 컴파일된 스키마를 읽습니다. 빌드 간에는 아무것도 유지되지 않으므로, 변경된 Feature 스키마는 다음 빌드에서 새로 컴파일됩니다.
바인딩 대상 검증(카탈로그 로드). 카탈로그 로드 시 컴파일러는 모든 Manifest features.annotations 바인딩을 순회하면서, maps.infra와 maps.values 아래에 선언된 모든 점 표기 경로가 참조된 Feature의 spec.schema.<pillar>가 실제로 선언하는 속성에 대응하는지 확인합니다. Feature 스키마에 없는 경로로 라우팅하는 바인딩은 바인딩 키, 누락된 경로, Feature URI, 소스 위치를 명시하는 명확한 OPS_ERROR와 함께 카탈로그 로드를 중단시킵니다.
스키마 필러 중복 린트(카탈로그 로드). Feature의 spec.schema가 infra와 values 필러 양쪽에 같은 속성 이름을 선언하면 권고 경고가 발생합니다. 이러한 중복은 의도된 경우가 드뭅니다. 필러 간에 이름이 같은 속성은 작성 의도를 모호하게 하고(어노테이션이 공유된 이름을 대상으로 할 때 어느 필러가 적용되는가?) 진단 메시지를 복잡하게 만듭니다. 이 경고는 차단하지 않으며 옵트아웃도 없습니다. 중복을 의도한 작성자는 중복과 경고를 그대로 두고, 의도하지 않은 작성자는 한쪽 필러의 속성 이름을 바꿉니다.
바인딩 맵 중복 린트(해석). Manifest의 바인딩 전반에서 하나의 하위 키 경로가 maps.infra와 maps.values 양쪽에 나타나면 권고 경고가 발생합니다. 두 필러 목록에 모두 나타나는 경로는 일관성이 없습니다. 하나의 어노테이션 하위 키는 두 필러로 동시에 라우팅될 수 없으며, 컴파일러가 적용하는 결정적 동점 처리(두 목록에 모두 나타나는 경로는 infra로 라우팅되고, Aggregate에 작성된 어노테이션은 values를 통해서만 라우팅될 수 있으므로 그곳에서 해당 경로에 작성된 어노테이션은 거부됨)는 안전망일 뿐 의도된 작성 형태가 아닙니다. 이 경고는 차단하지 않으며, 경고를 무시하고 실행하는 작성자도 깨끗한 빌드를 얻고, 동점 처리 결과는 IR 출처 정보에서 확인할 수 있습니다.
aggrega inspect 출처 정보 렌더링. inspect 명령은 Feature 연결마다 하나의 대괄호 표기를 렌더링하여 채워진 각 리프의 출처를 기록합니다.
[explicit]— Feature가 Aggregate 또는 Release의features:블록을 통해 명시적으로 연결되었습니다.[annotation: <key> from <source>]— 채워진 모든 리프가 같은 어노테이션 키에서 왔습니다. 대괄호 표기는 키와 어노테이션이 선언된 위치, 즉 파일과 그 안의 점으로 구분된 키 경로를 나타냅니다.- 리프별 대괄호 표기 — 양쪽을 조합한 경우로, 채워진 각 리프가 자체 출처 대괄호 표기와 함께 렌더링됩니다(일부는
[explicit], 일부는[annotation: <key> from <source>]). 이 형태는 필드 단위 명시 우선 병합을 드러냅니다. 명시적 연결과 어노테이션 기여가 같은 Component의 같은 Feature 인스턴스를 대상으로 하되 서로 다른 리프에 쓰는 경우, 두 기여는 각자의 리프에 그대로 유지되고 inspect 출력은 각 리프의 출처를 개별적으로 표시합니다.
inspect 렌더링은 IR의 필러별 values_provenance 및 infra_provenance 맵을 읽습니다. 이 맵은 어노테이션 확장 중 합성 연결 주입과 함께 채워집니다. 그런 다음 리프들의 전체 출처를 가장 잘 요약하는 대괄호 형태를 출력합니다. inspect 메커니즘은 특정 Feature 연결이 왜 특정 Component에 적용되었는지, 그리고 그 값이 어디에서 왔는지를 이해하기 위한 표준 내부 검사 수단입니다.