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

Wasm 플러그인 계약

Aggrega의 컴파일 파이프라인에는 WebAssembly(Wasm) 플러그인이 컴파일러의 동작을 확장하는 지정된 소켓 지점이 있습니다. 거버넌스 소켓의 네 가지 역할(그중에는 토폴로지 구성 단계의 Mutation Gate와 정적 분석 단계의 Validation Gate가 있음), FeatureRecipe 및 Recipe 단계를 위한 렌더링 후 플러그인 파이프라인, provider 렌더링 소켓, 파서 소켓, 임포터 소켓, 그리고 대역 외 린팅 소켓입니다. 이 페이지는 공개 Wasm 플러그인 계약을 설명합니다. 어떤 소켓이 있는지, 각 소켓이 무엇을 입력받고 무엇을 출력하는지, 각 소켓이 컴파일 파이프라인의 어디에 위치하는지, 그리고 모든 플러그인이 실행되는 샌드박스를 다룹니다.

이 페이지는 소켓, 즉 파이프라인 지점과 그 입출력 형태를 다룹니다. 플러그인, 즉 Plugin 엔터티, export별 capability 선언, 런타임 제한, publish→pull→build 수명 주기에 대해서는 Wasm 플러그인 개발자 가이드를 참조하십시오.

Aggrega는 Wasm 호스트 런타임(Wazero 엔진 위의 Extism)을 내장하며, 이 런타임은 AOT 순수성 방화벽 뒤에서 플러그인을 로드하고 실행합니다. 호스트는 게스트에게 주변 권한(ambient capability)을 전혀 부여하지 않습니다. 네트워크, 파일 시스템, 환경 변수가 없고, stdio는 버려지며, 관찰 가능한 벽시계는 빌드 불변 시점에 고정됩니다. 따라서 플러그인은 컴파일러의 AOT(ahead-of-time) 보장을 깨뜨릴 수 없습니다. 로드 시의 임포트 모듈 규칙, 인스턴스화 시의 거부, 선별된 호스트 함수를 포함한 전체 권한 범위는 아래의 샌드박스 계약에서 설명합니다. Plugin 작성자는 세 가지 언어(Go, Rust, TypeScript)의 PDK를 통해 호스트를 대상으로 개발합니다. aggrega lint는 린터 소켓, 즉 표준 게시 린터를 호스트를 통해 디스패치합니다. aggrega build는 워크스페이스가 거버넌스 소켓의 빌드 시점 역할을 구성한 경우 이를 디스패치합니다. 즉, 해석 단계의 어노테이션 변환 역할과 토폴로지 구성 단계의 레이블 변환 역할(둘 다 출력을 형성함), 그리고 정적 분석 단계의 IR 판정과 렌더링된 아티팩트에 대한 렌더 판정입니다. 각 역할은 해당 역할에 연결된 플러그인이 없으면 아무 작업도 하지 않으므로, 거버넌스 구성이 없는 빌드는 변경되지 않습니다. aggrega build는 또한 렌더링을 마무리하는 플러그인 파이프라인에서 FeatureRecipe 및 Recipe의 pipeline:을 디스패치합니다. 선언된 각 단계는 렌더링된 문서 집합을 대상으로 호스트를 통해 실행되며, 해당 단계의 RFC 6902 패치를 적용하고 부수 효과를 내보냅니다. 언어 현황 → 컴파일 파이프라인 단계를 참조하십시오.

샌드박스 계약

모든 소켓은 동일한 호스트 샌드박스를 통해 플러그인을 디스패치합니다. 샌드박스는 로드 시점의 구조 검사와 인스턴스화 시점의 기능 거부라는 두 개의 독립된 계층으로 이루어지며, 두 계층이 함께 플러그인이 접근할 수 있는 것, 접근할 수 없는 것, 그리고 플러그인이 책임져야 하는 것을 정의합니다.

임포트 모듈 규칙(로드 시점). 로더는 플러그인 바이너리의 임포트 섹션을 검사하여 세 가지 모듈 네임스페이스 아래의 함수 임포트만 허용합니다. wasi_snapshot_preview1(게스트 언어 런타임이 링크하는 WASI preview-1 런타임), extism:host/env(Extism 런타임 ABI — PDK 자체의 메모리 및 IO 내장 함수), extism:host/user(Aggrega가 선별한 호스트 함수)입니다. 게스트는 허용된 모듈 아래에서 어떤 함수 이름이든 임포트할 수 있습니다. 그 외의 모듈 아래의 임포트는 호스트가 제공하지 않는 표면을 가리키므로, 플러그인은 해당 모듈과 임포트를 명시하는 진단과 함께 로드 시점에 거부됩니다. 이 규칙은 의도적으로 개별 WASI 함수 이름을 검열하지 않습니다. 정적으로 링크된 언어 런타임은 실제 실행 경로에서 결코 호출하지 않는 파일 시스템 및 소켓 함수를 의존성을 통해 전이적으로 임포트하며, 임포트를 명시하는 것만으로는 아무 권한도 부여되지 않기 때문입니다. I/O가 없음을 보장하는 것은 임포트 검열이 아니라 인스턴스화 시점의 기능 거부입니다.

앰비언트 기능 없음(인스턴스화). 호스트는 실제 WASI 동작과 앰비언트 권한이 전혀 없는 상태로 게스트를 인스턴스화합니다.

  • 파일 시스템 없음 — 미리 열린 디렉터리가 없으므로 파일 시스템 호출은 호출 경계에서 실패합니다.
  • 네트워크 소켓 없음.
  • 빈 환경 변수.
  • 폐기되는 stdio — 게스트가 stdout이나 stderr에 쓰는 내용은 호스트의 스트림에 전달되지 않습니다.
  • 빌드 불변 시각에 고정된, 정지된 관측 가능 벽시계 — 시간을 읽는 게스트가 빌드 시각을 출력에 누출할 수 없습니다.
  • 실제로 진행하는 단조 시계 — 게스트 언어 런타임은 부트스트랩에 단조 시계가 필요하며, 단조 시간은 벽시계 시각이 아니라 경과 시간을 측정합니다.
  • 실제 호스트 엔트로피 — 엔트로피를 고정하면 언어 런타임의 내부 해시 시드가 안정화되어, 게스트의 비결정성이 서로 다른 출력으로 드러나지 않고 가려지게 됩니다.
  • argv로 전달되는 단일 합성 프로그램 이름.

게스트가 실제로 수행하는 I/O 호출 — 파일 열기, 소켓 연결 — 은 호출 경계에서 실패합니다. 이는 WASI 자체의 기능 기반 보안 모델로, 샌드박스는 코드를 감시하는 대신 기능 자체를 거부합니다.

입력은 페이로드와 선별된 호스트 함수를 통해서만 도착합니다. 플러그인은 렌더링하거나 평가하는 모든 것을 소켓이 전달하는 페이로드로 받습니다. 그래프 및 노드 프로젝션, 값, 렌더 컨텍스트가 여기에 해당합니다. 페이로드의 인코딩은 소켓마다 고정되어 있으며 아래 각 소켓의 섹션에 명시됩니다. 게시된 각 페이로드 타입은 해당 소켓의 인코딩을 위한 인코드 및 디코드 진입점을 함께 제공하므로, 게스트는 파서를 고르는 대신 함수 하나를 호출합니다. 소스 기반 provider 렌더의 경우 페이로드는 소스 바이트 대신 소스 목록을 전달합니다. 이는 노드의 소스 루트 아래에 있는 {path, is_dir} 항목의 정렬된 집합이며, 호스트는 provider 레이아웃을 해석하지 않습니다. 게스트는 자체 레이아웃 로직을 적용하여 — 단일 compose 파일을 선택하고, 차트 루트로 내려가고, Chart.yaml을 요구하고, 모듈을 재귀적으로 벤더링하는 등 — 선택한 부분만 정확히 호스트 콜백을 통해 읽어 옵니다. 페이로드 외에 호스트는 최소 권한으로 선별된 호스트 함수 집합을 바인딩하며, 플러그인에는 그 바이너리가 임포트하는 함수만 정확히 부여합니다.

  • aggrega_log — 호스트의 로그 대상에 기록되는 로그 한 줄.
  • aggrega_emit_warning — 호출 후 호스트가 표시하는 구조화된 경고.
  • aggrega_fetch_external_input — 외부 입력 가져오기 채널(아래 참조).
  • aggrega_pack_source — 소스 선택 콜백: 게스트가 소스 루트 아래의 {file | dir | tree, path} 선택을 지정하면, 호스트는 경로를 루트 아래로 해석하고 ..을 거부하는 샌드박스 안에서 정확히 그 부분을 읽어 패킹합니다.
  • aggrega_read_source_file — 내용에 따른 소스 선택을 위해 같은 샌드박스 안에서 수행하는 단일 파일 내용 읽기.
  • aggrega_parse_source — 생산자 소비 콜백: 게스트가 구문 형식을 지정하고 소스 바이트를 넘기면, 호스트는 그 형식의 파서를 결정하여 실행하고 파서가 생성한 정규 트리를 반환합니다. 이를 통해 소비자는 생산자 게스트를 직접 호출하지 않고 호스트를 거쳐 생산자의 출력을 얻습니다. 호스트는 이를 한 단계로 제한하므로 — 이 방식으로 호출된 생산자가 다시 호출하면 거부됩니다 — 소비자는 소스당 한 번 호출하며 여러 소스를 차례로 소비할 수 있습니다.

호스트는 플러그인이 임포트하는 집합을 .wasm 바이너리에서 도출하고, 선별된 허용 목록에 대해 검증하며, 게스트의 describe()가 선언하는 호스트 함수와 교차 확인합니다. aggrega plugin sync는 이 집합을 엔터티의 spec.runtime.hostFunctions에 기록하고, 게시 시에는 기록이 바이너리와 다른 엔터티가 거부됩니다. 따라서 모든 플러그인의 호스트 표면은 카탈로그에서 확인할 수 있으며 바이너리와 어긋날 수 없습니다.

콜백 실패는 hostfunc_error_code 아래에 기계가 대조할 수 있는 코드를 담습니다. 응답을 반환하는 호스트 콜백 — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file, 그리고 aggrega_parse_source 생산자 소비 콜백 — 은 실패를 대역 내로 전달합니다. 응답 봉투는 사람이 읽을 수 있는 메시지와 함께, 닫힌 어휘에서 가져온 기계 대조용 코드를 선택적으로 hostfunc_error_code 아래에 담습니다. 메시지는 사람을 위한 자유 형식 문장이고, 코드는 게스트가 메시지를 파싱하지 않고 분기할 수 있는 안정적인 식별자입니다. 성공 시에는 코드가 없고, 실패 시에는 호스트가 둘 다 설정합니다. PDK는 이 쌍을 타입이 지정된 오류로 제공하며, 그 텍스트는 메시지이고 코드 필드는 게스트가 언어별로 재export된 코드 상수와 대조합니다. 게스트는 코드가 없는 경우와 인식하지 못하는 코드를 메시지로 대체하여 처리합니다. 따라서 코드 대조는 항상 존재하는 메시지 위에 얹은 최선의 노력 수준의 세분화이며, 결코 메시지를 대체하지 않습니다. 닫힌 값 집합은 호스트 함수 오류 코드 스키마에 있습니다.

🔴 이 경계에서는 두 가지 다른 어휘가 실패를 명명하며, 읽는 키가 어느 쪽을 다루고 있는지 알려 줍니다. 둘을 혼동하는 것이 여기서 짚어 둘 만한 유일한 실수입니다. 어느 쪽의 값이든 평범한 문자열이고, 호스트도 게스트도 그 값이 어느 집합에서 왔는지 확인하지 않기 때문입니다.

  • hostfunc_error_code: 호스트가 게스트에 보내는 응답에 있습니다. 그 값은 위에 링크된 닫힌 카탈로그의 구성원으로, 호스트 콜백이 실패할 수 있는 방식을 명명하는 고정적이고 천천히 변하는 목록입니다. 집합이 닫혀 있으므로 게스트는 값을 키트가 재export하는 명명된 상수와 대조하여 그 결과에 따라 분기할 수 있습니다.
  • condition_code와 condition_short_code: 게스트가 호스트에 반환하는 소켓 출력에 있습니다. 이 둘은 게스트 자신이 발생시킨 중단 조건의 두 식별자이며, 카탈로그가 아니라 컴파일러가 등록하는 열려 있고 계속 늘어나는 조건 집합에서 옵니다. condition_code는 조건이 등록된 서술적 코드이고, condition_short_code는 독자가 인용하고 검색하고 보고서에 붙여 넣는 간결한 형식 — 문자 E와 네 자리 숫자 — 입니다. 호스트는 렌더링하는 진단의 대괄호 머리에 짧은 코드를 출력하므로, 게스트가 발생시킨 조건도 컴파일러가 발생시킨 조건과 똑같이 인용할 수 있습니다. 호스트는 어느 값도 도출하지 않지만 검사는 합니다. 짧은 코드가 이 컴파일러가 선언하지 않은 조건으로 해석되거나 번호가 폐기된 조건으로 해석되면, 아무것도 가리키지 않는 식별자로 독자에게 전달되는 대신 빌드가 중단됩니다.

게스트 측의 두 식별자는 함께 보고됩니다. 한쪽만 설정하고 다른 쪽을 설정하지 않은 게스트는 호스트가 확인할 수 없는 조건을 지정한 것이며, 이 경우 호스트는 대신 자체의 일반 플러그인 실패 조건을 보고하고 메시지에는 여전히 실패 전체가 담깁니다. 또한 condition_code는 호스트 함수 카탈로그의 구성원이 결코 아니므로, 이를 재내보내기된 상수와 비교해도 절대 일치하지 않습니다. 이것이 각 키가 실패 일반이 아니라 자신의 어휘를 지칭하는 이유입니다.

각 콜백의 슬롯은 명시된 인코딩을 가지며, 페이로드 문서를 담는 모든 슬롯은 이를 바이너리로 담습니다. 호스트 콜백이 받는 모든 인수는 aggrega_log의 숫자 레벨을 제외하면 게스트 메모리를 가리키는 포인터이며, 응답을 반환하는 콜백도 포인터로 응답합니다. 각 슬롯이 담는 내용은 콜백별로 고정되어 있습니다.

콜백인수 슬롯응답 슬롯
aggrega_log, aggrega_emit_warningUTF-8 텍스트 — 페이로드 문서 없음응답 없음
aggrega_fetch_external_input순수 UTF-8 URL — 페이로드 문서 없음정규 CBOR
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source정규 CBOR (RFC 8949 §4.2.1)정규 CBOR

이 표는 콜백의 정체가 아니라 각 슬롯이 담는 내용을 기준으로 나뉩니다. 페이로드 문서를 담는 슬롯은 정규 CBOR를 전달하고, 순수 문자열(로그 줄, 진단 필드, URL)을 담는 슬롯은 UTF-8 텍스트를 전달합니다. 두 슬롯이 서로 다른 것은 aggrega_fetch_external_input 하나뿐입니다. 이 콜백의 인수는 UTF-8 텍스트로 읽히는 순수 URL이고, 응답은 정규 CBOR로 된 페이로드 문서입니다.

페이로드를 전달하는 슬롯에서 게스트가 하는 일과 해서는 안 되는 일. 🔴 페이로드 문서를 담는 슬롯은 UTF-8 텍스트가 아닌 불투명한 바이트열을 담습니다. 따라서 이는 게스트가 그 자리에 넣는 바이트만이 아니라 게스트가 선언하는 형태이기도 합니다. 이러한 요청을 문자열로 할당하거나 이러한 응답을 문자열로 읽는 게스트는 상호 운용되지 않습니다. 어느 방향이든 텍스트 변환은 바이너리 바이트를 손상시킵니다. 이 실패는 부분적이지 않고 명확하게 드러납니다. 호스트가 디코딩할 수 없는 요청은 다른 콜백 실패와 같은 대역 내 형태로 request_undecodable 코드를 담은 응답 봉투로 돌아오므로, 게스트는 반쯤 읽은 페이로드로 진행하는 대신 이를 보고합니다. 페이로드 타입은 aggrega_pack_source에 대해 SourcePackRequest와 SourcePackResponse, aggrega_read_source_file에 대해 SourceFileRequest와 SourceFileResponse, aggrega_parse_source에 대해 ParseInput과 ParseSourceResponse이며, URL이 텍스트로 할당되는 aggrega_fetch_external_input에는 응답 타입 FetchExternalInputResponse만 있습니다. 키트별로 구체적으로는 다음과 같습니다.

  • Go — 요청 타입의 EncodeCBOR()로 요청을 만들고, pdk.AllocateString이 아닌 pdk.AllocateBytes로 할당하며, 응답 포인터가 가리키는 메모리에서 ReadBytes()로 응답을 읽어 응답 타입의 DecodeCBOR에 전달합니다. 요청 측에서는 fetch URL이 예외로, pdk.AllocateString으로 할당됩니다. 그 응답은 다른 응답과 같은 방식으로 읽습니다. //go:wasmimport 선언은 어느 경우든 포인터이므로 시그니처에는 형태가 드러나지 않으며, 형태는 할당과 읽기에 있습니다.
  • Rust — #[host_fn] 선언이 형태를 직접 나타냅니다. 세 페이로드 콜백은 각각 fn <callback>(request: Vec<u8>) -> Vec<u8>;이고, fetch 콜백은 fn aggrega_fetch_external_input(url: String) -> Vec<u8>;입니다. 요청 타입의 encode_cbor()로 요청을 만들고, 응답 타입의 decode_cbor(&raw)로 응답을 읽습니다.
  • TypeScript — 요청 타입의 encodeCBOR… 함수로 요청을 만들고, Memory.fromString이 아닌 Memory.fromBuffer로 할당하며, readBytes()로 응답을 읽어 응답 타입의 decodeCBOR… 함수에 전달합니다. fetch URL은 Memory.fromString으로 할당하며, 그 응답은 다른 응답처럼 readBytes()로 읽습니다. Go와 마찬가지로 declare module 항목은 어느 경우든 포인터입니다.

PDK 래퍼를 호출하는 게스트에는 이 모든 것이 필요 없습니다. 래퍼인 FetchExternalInput, PackSource, ReadSourceFile, ParseSource(각 언어의 표기법에 따름)가 할당과 인코딩을 수행하며, 어느 시그니처도 와이어 타입을 지칭하지 않으므로, 키트를 통해 이 콜백에 접근하는 게스트는 직접 아무것도 할당하거나 디코딩하지 않습니다. 호스트 함수를 직접 선언하고 호출하는 게스트는 위에서 설명한 대로 메모리를 할당하고 읽습니다. 텍스트로 할당된 요청은 반쯤 처리되는 대신 거부되고, 텍스트로 읽은 응답은 디코딩할 수 없으므로, 양측의 불일치는 조용히 넘어가지 않고 분명히 드러납니다.

신뢰할 만한 두 가지 속성이 있습니다. 응답은 성공하든 실패하든 같은 인코딩을 가집니다. 게스트는 하나의 슬롯을 읽으며 디코딩 전에는 둘 중 무엇이 담겼는지 알 수 없으므로, 하나의 디코딩 진입점이 둘 다 읽고 위에서 설명한 오류 코드와 메시지가 그것을 통해 도착합니다. 또한 게스트는 바이트 값 필드를 키트 자체의 필드 타입으로 채웁니다. Go에서는 바이트 슬라이스, Rust와 TypeScript에서는 base64 문자열입니다. 바이너리 인코딩이 전달하는 원시 바이트열로의 변환은 생성된 인코더의 몫이며, 나갈 때 수행되고 들어올 때 역변환되기 때문입니다. 여기에는 ParseInput의 소스 바이트, aggrega_read_source_file이 반환하는 파일 내용, aggrega_fetch_external_input이 가져온 내용, 그리고 pack-source 응답의 각 패킹된 파일 내용이 포함됩니다. 이 바이트는 이중 인코딩되지 않고 한 번만 경계를 넘으며, 어떤 게스트도 인코더가 곧 base64 디코딩할 것을 base64 인코딩하지 않습니다. read-source-file 및 fetch 응답의 content 필드는 비어 있으면 생략되므로, 빈 파일이나 길이가 0인 가져온 페이로드에 대한 응답은 내용을 전혀 담지 않습니다. 이러한 응답도 성공입니다. 실패는 항상 메시지와 코드를 담기 때문이며, 각 키트의 래퍼는 이에 대해 빈 바이트를 반환합니다. aggrega_parse_source가 반환하는 트리는 자체 JSON 문서를 그대로 담은 바이트열로 전달되며, 호스트는 이를 읽지도 재구성하지도 않습니다. 파서는 자체 parse 내보내기에서 같은 인코딩으로 같은 ParseInput을 읽습니다. 파서 소켓을 참고하십시오.

정규라는 것은 동일한 입력이 모든 측에서 동일한 바이트를 생성한다는 뜻이며, 이 덕분에 페이로드를 왕복 변환만이 아니라 세 플러그인 키트 간에 비교할 수 있고, 빌드 출력이 바이트 단위로 동일하게 유지됩니다. 게스트에는 CBOR 라이브러리가 필요 없고 바이트를 직접 파싱하는 일도 없습니다. 게시된 각 페이로드 타입이 해당 슬롯의 인코딩에 필요한 인코딩 및 디코딩 진입점을 함께 제공합니다.

결정성은 플러그인 작성자의 책임입니다. 호스트는 게스트의 출력 바이트를 그대로 소비하며 그 위에 직렬화기를 실행하지 않으므로, 모든 플러그인이 지켜야 할 계약은 동일한 입력이 동일한 출력 바이트를 생성한다는 것입니다. 샌드박스는 비결정성의 주변 원천(벽시계 시간, 환경, 파일 시스템 상태)을 제거하지만, 나머지는 의도적으로 가리지 않습니다. 엔트로피나 경과한 단조 시간을 출력에 인코딩하는 게스트는 안정적으로 숨겨진 결함이 아니라 실행마다 눈에 띄게 달라지는 바이트를 생성합니다.

외부 입력 fetch 채널. aggrega_fetch_external_input은 원격 콘텐츠를 위해 허용된 유일한 채널이며, 게스트의 네트워크 접근이 아니라 호스트가 중개합니다. 게스트가 URL을 지정하면 호스트는 외부 입력 고정 원칙에 따라 바이트를 제공합니다. Release의 lockfile에 고정된 URL은 로컬 콘텐츠 주소 지정 저장소에서 제공되고 기록된 다이제스트와 대조하여 검증됩니다. 고정되지 않은 URL은 해당 URL과 이를 고정하는 단계를 명시한 진단과 함께 거부됩니다. 렌더는 lockfile이 기록한 클로저를 소비하며 결코 확장하지 않기 때문입니다. 고정은 Release의 의존성이 해석될 때 기록되며, 이때가 무엇이든 고정되는 유일한 순간입니다. 개발자 가이드에 작성 방법과 고정 원칙이 모두 나와 있습니다.

순서를 유지하는 맵

페이로드가 담는 일부 맵은 해당 소켓의 스키마에서 순서 보존으로 표시됩니다. 항목의 순서가 그 맵이 담는 내용의 일부이기 때문입니다. 빌드의 노드, 노드의 레이블, 노드의 첨부, 파이프라인 단계의 입력과 출력, provider가 선언하는 키 공간이 그 예입니다. 게시된 페이로드 타입은 이러한 맵을 각각 항목이 설정된 순서대로 유지하는 컨테이너에 담습니다.

키트컨테이너
Goaggrega.OrderedMap[V] — ABI 패키지의 abi.OrderedMap[V]에 대한 키트의 이름
Rustaggrega-abi crate의 OrderedMap<V>, 키트가 다시 내보냄
TypeScript언어 자체의 Map<string, V>

Go와 Rust 컨테이너는 맵의 연산을 제공합니다. 키 조회, 설정, 삭제, 키 읽기, 항목을 순서대로 순회하기, 개수 세기입니다. 컨테이너에 이미 있는 키를 설정하면 값이 교체되고 위치는 유지됩니다. 새 키는 기존의 모든 키 뒤에 추가됩니다.

순서는 두 인코딩 모두에서 유지됩니다. 바이너리 인코딩에서 표시된 맵은 컨테이너의 순서대로 항목의 순서 있는 목록으로 기록됩니다. 각 항목은 키와 값으로 이루어진 두 요소 목록입니다. 그렇지 않으면 정규 인코딩은 키를 정렬한 맵으로 기록합니다. 텍스트 인코딩에서는 멤버가 컨테이너의 순서대로 기록된 JSON 객체입니다. 어느 인코딩의 디코더든 키가 중복된 맵은 해당 키를 명시하며 거부합니다. 스키마가 표시하지 않은 맵은 바이너리 인코딩에서 정렬된 맵 형태를 유지하며, 게시된 타입에서는 언어의 일반 맵 타입이 됩니다.

게스트에 대한 세 가지 결과는 다음과 같습니다.

  • 순서도 출력입니다. 표시된 맵은 채워진 순서대로 기록되므로, 고정된 순서가 없는 소스(예: Go 내장 맵 순회)에서 맵을 채우는 게스트는 동일한 입력의 실행마다 다른 바이트를 기록합니다. 고정된 순서로 채우십시오.
  • 순서는 맵이 컨테이너 안에 있는 동안에만 유지됩니다. 페이로드를 자기 언어의 범용 값 타입으로 변환하는 게스트는 그 타입의 순서를 따르게 됩니다. Go의 map[string]any에는 순서가 없고, Rust의 serde_json::Value는 crate를 preserve_order 기능으로 빌드하지 않는 한 객체 키를 정렬된 상태로 유지합니다.
  • TypeScript에서는 생성된 함수를 통해 읽고 쓰십시오. 표시된 맵을 담는 타입은 JSON을 멤버 단위로 디코딩하므로, "8080"처럼 배열 인덱스로 읽히는 키도 제자리를 유지합니다. JSON.parse라면 이 키를 객체의 맨 앞으로 옮깁니다. 또한 그 인코더는 각 Map을 객체로 기록하는 반면, JSON.stringify는 Map을 {}로 기록합니다. Map의 Object.keys도 비어 있으므로, Map의 키는 자체 keys()로 읽으십시오.

입력이 민감하다고 표시한 값

플러그인은 반환하는 거부나 경고에서, 입력이 민감하다고 표시한 값을 절대 인용하지 않습니다. 키로 표시된 값이든, 전체가 표시된 페이로드의 일부인 값이든 마찬가지입니다. 거부는 출력이 담는 error이고, 경고는 심각도와 관계없이 출력이 담는 Diagnostic 또는 aggrega_emit_warning을 통해 발생한 경고입니다. 호스트는 이 텍스트를 보고하는 모든 곳(명령줄, 언어 서버와 편집기의 문제 목록, 어시스턴트 도구)에 변경 없이 전달하며 그 안에서 어떤 값도 읽어 내지 않으므로, 값을 빼낼 수 있는 당사자는 플러그인뿐입니다. 대신 키, 설정 또는 위치를 명시하십시오. 읽는 사람은 그곳에서 값을 찾습니다.

이 규칙은 플러그인이 직접 작성하는 텍스트뿐 아니라 라이브러리가 플러그인을 위해 작성하는 텍스트에도 똑같이 적용됩니다. 템플릿 엔진은 평가하던 데이터를 보고하고, 스키마 검증기는 pattern에 맞지 않는 값을 인용하며, 파서는 읽지 못한 토큰을 인용합니다. 그러한 실패가 입력이 표시한 값에서 발생했다면 값 없이 보고하십시오. 예를 들어 표시된 모든 값을 자리 표시자로 바꾸어 같은 단계를 다시 실행하고, 그 실행이 같은 위치에서 실패하면 그 실행의 실패를 보고하며, 그렇지 않으면 실패 텍스트가 보류되었다고 알립니다. 전체가 표시된 페이로드에서는 그 페이로드의 모든 값이 표시된 값이지만, 키(문서의 형태)는 읽을 수 있는 상태로 남습니다.

입력이 키 또는 페이로드를 민감하다고 표시하는 위치는 다음과 같으며, 와이어에서 쓰는 이름으로 표기합니다.

소켓과 익스포트표시를 읽는 위치
provider render_node 및 validate_node_input (RenderNodeInput)node.sensitive_rendered_keys: 각 키는, 그 값이 Component 자신의 값이고 Component가 선언한 리프를 키로 하는 경우 node.values의 항목을 가리키거나(Recipe의 valuesMapping은 어떤 선언도 이름 붙이지 않은 키를 쓰므로 여기서는 그중 어느 것도 표시되지 않습니다), 민감하다고 선언된 슬롯을 읽는 워크로드 컨테이너의 attachments 맵 항목을 가리킵니다. node.sensitive_values는 node.values 전체를 표시합니다. 그 값을 만든 valuesMapping(Recipe의 것이든 어태치먼트의 FeatureRecipe의 것이든)이 작성자가 민감하다고 선언한 값을 읽으면 true입니다. workload_projection.sensitive_workload는 워크로드의 템플릿이 그런 값을 읽을 때 같은 방식으로 워크로드의 모든 값을 표시하고, artifacts_projection.entries의 각 항목은 자체 콘텐츠에 대해 sensitive_content를 가지며, 여기에는 그 콘텐츠에 관한 파서의 메시지도 포함됩니다. omits의 각 항목은 그 kind, name, namespace 중 어느 하나를 만드는 템플릿이 그런 값을 읽을 때 sensitive를 가지며, 이때 그 항목의 모든 필드는 표시된 값입니다. node.features의 각 항목은 자기 어태치먼트의 표시를 가집니다: sensitive_payload_leaves(해당 Feature가 민감하다고 선언한 values.<path> 및 infra.<path> 리프), sensitive_inject(해당 Feature가 민감하다고 선언한 provides 키를 읽는 inject 전달 키), sensitive(어태치먼트가 민감하다고 선언된 자료를 조금이라도 다루는지 여부).
governance ir-verdict (PolicyInput)graph: 각 노드의 sensitive_payload_leaves, 그리고 각 어태치먼트의 sensitive_payload_leaves, sensitive_inject, sensitive입니다. 이 표시들이 가리키는 모든 값은 이미 보류 마커 {"aggrega_withheld": "declared"}로 도착하므로, 값 자체는 플러그인에 절대 도달하지 않습니다.

그 밖의 소켓 입력이나 다른 provider 익스포트의 입력은 표시를 가지지 않습니다. 키 표시는 선언에 정확히 결합되는 것만 가리키므로, 키가 없다고 해서 값을 인용해도 안전하다는 뜻이 되지는 않습니다. 이는 어떤 선언도 그 키에 결합될 수 없었다는 뜻입니다. 페이로드 표시는 값이 아니라 페이로드를 생성한 템플릿의 참조(선언된 값에 도달하는 참조, 데이터 전체를 넘겨주는 템플릿, 또는 파싱되지 않는 템플릿)에서 읽으므로, 표시가 없다는 것은 참조로 보이는 한 그 템플릿이 선언된 값을 읽지 않았거나 어떤 템플릿도 페이로드를 생성하지 않았다는 뜻일 뿐, 페이로드에 민감한 것이 없다는 진술이 아닙니다.

Wasm 소켓의 파이프라인 배치

컴파일 파이프라인은 다음 소켓 지점을 예약합니다. 형태 레이블은 Status 페이지의 네 가지 레이블 분류 체계를 따릅니다.

소켓파이프라인 배치현재 상태
거버넌스 소켓, annotation-transform 역할해석(어노테이션 확장 이전)사용 가능 — 워크스페이스가 annotation-transform 플러그인을 연결하면 디스패치되며, 확장 과정에서 Feature 연결로 바뀌는 어노테이션을 주입합니다
거버넌스 소켓, label-transform 역할토폴로지 구성(Topology Builder)사용 가능 — 워크스페이스가 label-transform 플러그인을 연결하면 디스패치되며, JSON Patch로 노드 레이블을 자동 태깅합니다
거버넌스 소켓, ir-verdict 역할정적 분석(Static Analyzer, IR 그래프 대상)사용 가능 — 워크스페이스가 ir-verdict 플러그인을 연결하면 디스패치되며, halt 판정은 빌드를 중단합니다
거버넌스 소켓, render-verdict 역할렌더링(렌더링된 아티팩트 대상)사용 가능 — 워크스페이스가 render-verdict 플러그인을 연결하면 디스패치되며, halt 판정은 빌드를 중단합니다
FeatureRecipe 및 Recipe pipeline: 플러그인플러그인 파이프라인(렌더링 후 변경)사용 가능 — 선언된 각 단계가 렌더링된 문서 집합에 대해 실행되어 RFC 6902 패치를 적용하고 부수 효과를 내보냅니다
Provider 렌더링 플러그인(helm, helm-chart, compose, terraform, cloudformation)기본 렌더링(프로바이더)사용 가능 — 모든 프로바이더는 자신의 Wasm 게스트를 통해 렌더링합니다. 렌더링은 Wasm 전용이며 호스트 내 렌더러 대체 경로는 없습니다
파서 플러그인(parse:<format>)렌더링(render-verdict 정책용), 그리고 대역 외(가져오기용)사용 가능 — render-verdict 정책이 기본적으로 읽지 못하는 형식의 아티팩트에 대해, aggrega_parse_source를 통해 임포터를 위해, 그리고 형식을 지정하지 않은 가져오기의 형식을 인식하기 위해 호출됩니다
임포터 플러그인(import:<format>)대역 외(aggrega import)사용 가능 — aggrega import, 편집기 세션, 어시스턴트용 도구가 디스패치합니다
린터 플러그인(linter/publishing)대역 외(aggrega lint)사용 가능 — publishing-linter가 함께 제공되며 aggrega lint를 통해 호스트에서 실행됩니다

해석 단계의 일부인 어노테이션 기반 Feature 확장 하위 단계는 Wasm 소켓이 아니라 네이티브 Go 파이프라인 패스입니다. 이 단계는 대상 Feature의 spec.schema에 대해 어노테이션 값을 검증하고 IR 빌드 시점에 합성 Feature 연결을 주입합니다. 어노테이션과 레이블을 지니는 여섯 가지 표면은 vocabulary/labels-and-annotations.md를, 바인딩 형태와 작성 안내는 providers/well-known-annotations.md를 참조하십시오.

출력 형태 계약 — 현재 존재하는 것

거버넌스 소켓은 네 가지 역할마다 타입이 지정된 계약 표면을 가지며, 어느 표면인지는 역할이 정합니다. Plugin 작성자는 문서화된 형태를 생성하는 게스트 측 코드를 구현합니다. 워크스페이스가 해당 역할에 플러그인을 연결하면, 호스트는 빌드 시점에 구성된 플러그인마다 한 번씩 그 형태를 읽습니다. 아래 하위 절은 파이프라인이 역할을 디스패치하는 순서를 따릅니다.

annotation-transform 역할 — 어노테이션 주입 출력

파이프라인 배치. 해석 단계에서, 컴포넌트가 해석된 후 어노테이션 기반 Feature 확장이 실행되기 전입니다.

입력 형태(호스트 → 게스트). 다음을 담은 AnnotationTransformInput 문서입니다.

  • targets — 주입 대상: 게스트가 어노테이션을 추가할 수 있는 해석된 컴포넌트(경계가 직접 지정하는 컴포넌트와, 경계의 aggregates: 아래 라우팅 항목이 라우팅해 들이는 모든 컴포넌트로, 항목이 그것을 지정하는지와 관계없음)이며, 각각 boundary_path, component_name(라우팅된 컴포넌트의 경우 metrics.query처럼 빌드 그래프에서의 점으로 구분된 ID), 그리고 Release가 그 위에 작성한 annotations를 담고 있으므로 게스트는 작성된 값을 밀어내지 않고 무엇을 추가할지 결정할 수 있습니다. 각 어노테이션 값은 작성된 그대로 도착합니다. 문자열, 하위 키의 객체, 또는 컴포넌트가 상속받을 어노테이션에서 빠지는 경우 null이며, 컴포넌트가 가진 모든 키는 값과 관계없이 존재합니다. 호스트가 결정적으로 정렬합니다.
  • binding_keys — Manifest가 바인딩을 등록한 어노테이션 키이며, 작성자 순서를 따릅니다. 등록된 키로 이루어진 주입은 이어서 Feature 연결로 확장되므로, 게스트는 이 목록을 읽어 효력을 가질 키를 주입합니다. 호스트는 주입이 등록된 키를 지정할 것을 요구하지 않습니다. 등록되지 않은 주입 어노테이션은 작성된 바인딩 없는 어노테이션과 정확히 같이 동작합니다.
  • sources — 연결이 with.sources 아래에 선언한 정의 파일이며, 각각 기본 이름 경로와 내용을 담고 경로순으로 정렬됩니다.
  • settings — 연결이 with.settings 아래에 선언한 자유 형식 설정 객체이며, 그대로 게스트에 전달됩니다.

settings와 sources는 다른 모든 역할이 읽는 것과 같은 엔진에 구애받지 않는 with 채널이며, 연결이 아무것도 선언하지 않으면 둘 다 없습니다. 이 역할의 출력이 빌드를 형성하므로, 연결의 설정과 소스 내용은 pull 시 release 잠금 파일에 고정되고 빌드 시 그로부터 재구성됩니다.

출력 형태(게스트 → 호스트). 다음을 담은 AnnotationTransformOutput 문서입니다.

  • injections — 추가할 어노테이션이며, 순서를 따릅니다. 각 항목은 기존 대상 좌표(boundary_path와 component_name)와 함께 annotation_key 및 그 annotation_value를 지정합니다. 값은 문자열이거나, 여러 하위 키를 한 번에 라우팅하는 바인딩에 전달되는 하위 키의 객체입니다.

호스트는 어노테이션 추가만 적용하며, 자신이 제공한 좌표에만, 그리고 작성자가 그 어노테이션에 작성할 수 있는 값으로만 적용합니다. 주입된 값은 Release에 작성된 같은 값을 읽는 것과 정확히 같은 방식으로 읽히므로(객체의 하위 키는 게스트가 작성한 순서대로), 확장은 이를 작성된 어노테이션과 똑같이 다룹니다. 페이로드에 없는 좌표를 지정하거나 null, 목록, 숫자, 불리언 또는 하위 키가 없는 객체를 담은 주입은 조용히 버려지거나 적용되지 않고, 좌표와 어노테이션을 명시하는 메시지와 함께 빌드를 중단합니다. 출력의 어느 부분이든 적용하기 전에 출력 전체를 검사합니다. 이러한 제한이 이 역할의 범위를 정합니다. 여기에 플러그인을 연결하는 운영자는 어노테이션 주입을 선언한 것이며, 그 이상은 아닙니다. 이후 빌드가 주입된 어노테이션을 그 라우팅 방식, 바인딩된 Feature의 스키마가 허용하지 않는 하위 키 값, 또는 Release 측 어노테이션이 사용할 수 없는 기둥 때문에 거부하는 경우, 그 메시지는 이를 주입한 플러그인과 그 플러그인이 연결된 역할을 명시합니다.

와이어 인코딩. 이 역할의 페이로드와 결과는 양방향 모두 정규 CBOR(RFC 8949 §4.2.1)로 전달됩니다. 게스트는 페이로드 타입이 제공하는 진입점 — Go의 DecodeCBOR와 EncodeCBOR, Rust의 decode_cbor와 encode_cbor, TypeScript의 decodeCBORAnnotationTransformInput와 encodeCBORAnnotationTransformOutput — 을 통해 이를 읽고 쓰므로, CBOR 라이브러리가 필요 없고 바이트를 직접 파싱하지도 않습니다. Rust에서 export는 Vec<u8>를 받고 반환하며, TypeScript에서는 Host.inputBytes()를 읽고 Host.outputBytes(...)를 씁니다. 각 대상의 annotations는 스키마가 순서 보존으로 표시한 맵이므로, 대상이 보유한 순서대로 항목의 순서 있는 목록으로 전달되며, 게스트는 kit의 순서 유지 컨테이너를 통해 이를 읽습니다. 각 값은 그 JSON의 바이트로 전달되며, 이는 반대 방향에서 주입의 annotation_value가 전달되는 방식과 같습니다. settings는 JSON 문서의 바이트로 전달되며, 게스트는 내부를 보려면 이를 JSON으로 파싱합니다. 이 인코딩의 AnnotationTransformOutput가 아닌 응답 — JSON으로 작성되었거나 형태가 선언하지 않은 최상위 필드를 담은 응답 — 은 빈 주입 목록으로 읽히는 대신 플러그인과 그 export를 명시하며 빌드를 중단합니다. aggrega plugin run-local --export transform_annotations로 직접 호출하면, 게스트에는 작성된 JSON 페이로드가 이 인코딩으로 변환되어 전달되고, 응답은 export의 출력 형태로 읽혀 JSON으로 출력됩니다. 그 형태가 아닌 응답은 빌드가 거부하는 것과 같이 export를 명시하며 거부됩니다.

타입 정의. annotation-transform 와이어 타입 — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — 은 세 ABI 패키지 모두에 게시되며, 하나의 코덱에서 생성되므로 세 패키지가 항상 일치합니다.

label-transform 역할 — JSONPatch 출력

파이프라인 배치. 토폴로지 구성 단계로, 그래프가 평탄화된 후 IR 그래프가 빌드되기 전입니다. 따라서 분석기가 평가하는 소켓 및 Feature 선택자는 이 역할이 남긴 레이블을 읽습니다.

입력 형태(호스트 → 게스트). 다음을 담은 MutatorInput 문서입니다.

  • compilation_context — 릴리스 식별 정보(release_name, environment).
  • graph — 토폴로지 노드의 MutatorGraph 투영: 각 노드의 Component, 해석된 버전, 레이블, 그리고 그 인스턴스가 선언하는 values.
  • settings — 연결이 with.settings 아래에 선언한 자유 형식 설정 객체이며, 그대로 게스트에 전달됩니다.
  • sources — 연결이 with.sources 아래에 선언한 정의 파일로, 각각 기본 이름 경로와 내용을 담습니다. 따라서 mutator는 인라인 설정 대신 체크인된 규칙 파일이나 매핑 파일로 구동될 수 있습니다.

그래프는 IR 그래프가 아니라 투영입니다. 각 노드는 확인된 레이블 집합과 그 인스턴스가 Aggregate에서 선언하는 값을 담고, 엣지와 feature 페이로드는 컴파일러 내부에 남습니다. 값은 Aggregate 자체의 값으로, 그 템플릿은 이미 파라미터에 대해 평가되었으므로 파라미터로 끌어올려진 값은 Release가 제공한 값으로 도착합니다. Component의 스키마가 선언하는 기본값과 Recipe나 Feature가 기여하는 것은 포함되지 않으며, 값을 선언하지 않는 노드는 values 키를 갖지 않습니다. 노드의 Component가 민감하다고 선언하는 값은 그래프에 대한 판정이 보류하는 것과 정확히 같이 보류되어 {"aggrega_withheld": "declared"}로 읽히며, 어떤 선언도 미치지 않는 형제 값은 모두 작성된 그대로 도착합니다. 이 덕분에 개발자가 선언한 구성이 레이블을 결정할 수 있습니다. 예를 들어 값으로 벡터 확장을 활성화한 데이터베이스를 datastore.aggrega.ai/engine: vector로 승격하는 식입니다. settings와 sources는 판정 역할이 읽는 것과 동일한 엔진에 구애받지 않는 with 채널이며, 호스트는 이를 그대로 전달할 뿐 내용을 해석하지 않습니다. mutator의 출력이 빌드를 형성하므로, 연결의 설정과 소스 내용은 pull 시 릴리스 lockfile에 고정되고 빌드 시 그로부터 재구성됩니다. 따라서 mutator 입력은 다음 pull 전까지 pull 이후 어느 쪽에 생긴 변경에도 영향을 받지 않습니다.

출력 형태(게스트 → 호스트). 다음을 담은 MutatorOutput 문서입니다.

  • patches — 호스트가 노드 레이블에만 적용하는 불투명한 JSONPatch 문서(RFC 6902)의 배열이며, 입력이 담고 있던 값은 읽기 전용입니다.

각 패치는 JSON Pointer (RFC 6901)를 통해 특정 노드의 레이블을 지정합니다. 호스트는 패치를 배열 순서대로 적용하고 변경된 레이블 집합을 IR 그래프에 다시 반영합니다. label-transform 역할의 목적은 엔터프라이즈 자동 태깅으로, 카탈로그 내용을 수정하지 않고 엔터프라이즈 정책이 선언한 규정 준수 / 관측성 / 비용 귀속 레이블을 추가하는 것입니다. 레이블 영역은 이 역할이 허용하는 유일한 대상입니다. 노드의 레이블이 아닌 필드를 건드리거나, 노드를 추가 또는 제거하거나, 문자열이 아닌 레이블 값을 설정하는 패치는 조용히 흡수되지 않고 빌드를 중단시킵니다. RFC 6901은 Aggrega의 모든 문서 경로 영역에 대한 경로 문법 기준입니다. 여기의 Wasm 플러그인 계약, .locals *_path 내보내기, 그리고 문서 전반의 *Path 스키마 필드가 이에 해당합니다. 정식 기준 선언과 두 작성 측을 구분하는 *Path / *_path 접미사 규율은 02-naming-conventions.md의 “Document-path naming-suffix discipline”을 참조하십시오.

전송 인코딩. 이 역할의 페이로드와 결과는 양방향 모두 정규 CBOR(RFC 8949 §4.2.1)로 전달됩니다. 정규란 동일한 입력이 모든 쪽에서 동일한 바이트를 만든다는 뜻이며, 덕분에 페이로드를 왕복 변환만이 아니라 세 플러그인 키트 간에 비교할 수 있고, 빌드 출력이 바이트 단위로 동일하게 유지됩니다. 게스트는 키트의 페이로드 타입이 이미 제공하는 진입점, 즉 Go의 DecodeCBOR와 EncodeCBOR, Rust의 decode_cbor와 encode_cbor, TypeScript의 decodeCBORMutatorInput과 encodeCBORMutatorOutput을 통해 읽고 쓰므로 CBOR 라이브러리가 필요 없고 바이트를 직접 파싱할 일도 없습니다. Rust에서 내보내기는 Vec<u8>을 받고 반환하며, TypeScript에서는 Host.inputBytes()를 읽고 Host.outputBytes(...)를 씁니다. 그래프의 nodes, 각 노드의 labels, 각 노드의 values는 스키마가 순서 보존으로 표시한 맵이므로 항목의 순서 있는 목록으로 전달됩니다. 노드는 빌드가 보유한 순서, 즉 작성 순서로, 각 노드의 레이블은 노드가 담은 순서로, 각 노드의 값은 Aggregate가 작성한 순서로 전달되며, 게스트는 셋 모두 키트의 순서 유지 컨테이너를 통해 읽습니다. 각 값은 그 JSON 문서의 바이트로 전달됩니다. Go와 Rust 키트는 이를 그 JSON 그대로 게스트에 넘겨 규칙에 필요한 만큼 파싱하게 하고, TypeScript 키트는 파싱된 값으로 넘깁니다.

이것이 바꾸지 않는 것이 두 가지 있습니다. patches 배열은 JSON으로 유지됩니다. 소켓은 각 패치 문서를 불투명한 내용으로 그대로 전달하며 어느 쪽도 그 안을 읽지 않으므로, 패치 문서 자체의 형태는 소켓이 전달하는 인코딩과 무관합니다. 또한 settings와 sources는 여전히 그대로 전달됩니다. settings는 연결이 작성한 바이트로 도착하며, 게스트는 내용을 살펴봐야 할 때 이를 JSON으로 파싱합니다.

다른 모든 거버넌스 역할도 동일한 인코딩을 사용합니다. annotation-transform 역할과 두 판정 역할이 각자의 섹션에서 이를 밝힙니다. 따라서 둘 이상의 역할을 담당하는 게스트는 담당하는 모든 역할에서 정규 CBOR를 사용하며, 각 페이로드를 해당 타입의 디코드 진입점을 통해 읽습니다.

타입 정의. mutator 전송 타입인 MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode는 세 ABI 패키지(github.com/aggrega-ai/aggrega-abi/go, aggrega-abi crate, @aggrega-ai/aggrega-abi) 모두에 게시되며, 하나의 코덱에서 생성되므로 세 패키지가 항상 일치합니다. 호스트는 입력을 구성하고 게스트가 반환한 패치를 적용합니다.

verdict 역할 — verdict 배열 출력

정책 게스트는 빌드를 검사하고 verdict 목록을 반환합니다. 호스트는 각 verdict의 심각도에 따라 동작하며 정책 자체를 해석하지 않습니다. 네 가지 역할, 심각도, 운영자가 제공하는 입력 채널, 컴파일러에 포함된 두 엔진 중 하나를 위한 정책 작성, 외부 정책 엔진 래핑, 참조 게스트, 운영자가 정책을 연결하는 방법 등 전체 내용은 거버넌스 소켓 페이지에 있습니다. 이 절에서는 파이프라인 배치와 타입이 지정된 와이어 형태를 기록합니다.

파이프라인 배치. 정책은 정확히 하나의 verdict 역할에 연결되며, 이 역할이 정책의 평가 위치를 정합니다.

  • ir-verdict — 정적 분석 시점, 기본 렌더링 전에 평가됩니다. 분석기는 모든 빌드에서 페이로드를 조립합니다.
  • render-verdict — 렌더링 후 생성된 아티팩트를 대상으로 평가됩니다.

워크스페이스가 verdict 역할 플러그인을 연결하면, 파이프라인은 해당 역할의 페이로드를 플러그인에 마샬링하고 그 verdict를 다시 읽어 들입니다.

입력 형태(호스트 → 게스트). 역할에 따라 페이로드가 정해집니다.

  • ir-verdict PolicyInput은 graph(Topology Builder가 생성하는 것과 같은 형태로, 컴파일러가 보유한 모든 노드, 엣지, 연결 세부 정보를 담은 capability에 구애받지 않는 전체 IR 그래프. 단, 작성자가 민감하다고 선언한 값은 보류된 상태로 도착합니다. 입력이 민감하다고 표시하는 값 참조)와 precalculated_paths(분석기가 함께 열거하는 라우팅 경로)를 전달하므로, 정책은 그래프를 다시 순회하지 않고도 도달 가능성을 추론할 수 있습니다. 이 그래프는 ir-v1beta1 스키마를 단일 출처로 하는 버전 관리된 IR 그래프입니다. IR 형태는 비밀이 아니며(aggrega inspect가 출력하는 것과 같은 그래프입니다), 그 안의 시크릿은 평문이 아니라 항상 포인터입니다.
  • render-verdict RenderPolicyInput는 artifacts를 전달합니다. 이는 경로순으로 정렬된 렌더링 출력 파일이므로, 동일한 입력으로 여러 번 실행해도 와이어가 바이트 단위로 동일합니다. 각 항목은 아티팩트의 출력 path와 렌더링된 content를 전달합니다. 또한 생성한 provider가 형식을 선언한 경우 렌더링에 사용된 format을 전달하고, 게스트가 네이티브로 읽지 못하는 형식의 파싱된 정규 뷰인 tree도 전달합니다. 이 트리는 호스트가 해석된 파서로 파싱하여 불투명하게 그대로 전달합니다. 둘 다 해당하지 않으면 생략됩니다. 게스트가 네이티브로 읽는 형식(JSON, YAML)은 파싱되지 않은 채로 남아 게스트가 content에서 읽습니다.

두 역할 모두 연결의 sources(호스트가 빌드 시점에 읽어 게스트에 그대로 넘기는 정책 정의 파일로, 경로는 기본 이름이고 내용은 불투명함)와 settings(손대지 않고 전달되는 자유 형식 객체)를 추가로 전달합니다. 연결이 아무것도 선언하지 않으면 둘 다 생략됩니다.

출력 형태(게스트 → 호스트). 다음을 담은 PolicyOutput 문서입니다.

  • results — Diagnostic 항목의 배열이며, 각 항목은 severity(halt, warn 또는 info)와 message 문자열을 가집니다. verdict는 같은 항목에 code, rule_id, classification, source_ref, location, suggest도 설정할 수 있습니다. 호스트는 모든 심각도 경로에서 verdict가 가진 이들 필드를 렌더링된 verdict에 덧붙입니다.

발생한 verdict만 나타나며, 허용하는 평가는 빈 배열을 반환합니다. 호스트는 verdict를 순회하며 각 심각도를 동작에 대응시킵니다. halt는 빌드를 중단하고(모든 halt 메시지를 표시), warn은 verdict를 표시하고 빌드를 계속 진행하며, info는 결과에 영향을 주지 않고 기록합니다. halt는 selector 또는 appliesTo 위반이 사용하는 것과 같은 게이트를 통해 중단됩니다.

와이어 인코딩. 두 역할의 페이로드와, 어느 역할에서든 게스트가 반환하는 PolicyOutput은 정규 CBOR(RFC 8949 §4.2.1)로 전달됩니다. 게스트는 페이로드 타입이 가진 진입점, 즉 Go의 DecodeCBOR와 EncodeCBOR, Rust의 decode_cbor와 encode_cbor, TypeScript의 decodeCBORPolicyInput, decodeCBORRenderPolicyInput, encodeCBORPolicyOutput을 통해 읽고 쓰므로, CBOR 라이브러리가 필요 없고 바이트를 직접 파싱할 일도 없습니다. Rust에서는 각 export가 Vec<u8>을 받고 반환하며, TypeScript에서는 Host.inputBytes()를 읽고 Host.outputBytes(...)를 씁니다. 그래프의 순서 보존 맵(그래프의 nodes와 각 노드의 labels 포함)은 빌드가 보유한 순서대로 항목의 순서 있는 목록으로 전달되며, 게스트는 kit의 순서 유지 컨테이너로 이를 읽습니다. 각 정책 엔진에서 정책이 이들을 어떤 순서로 접하는지는 거버넌스 소켓 페이지에 있습니다. settings와 아티팩트의 파싱된 tree는 JSON 문서의 바이트로 전달되며, 게스트는 내용을 보려면 JSON으로 파싱합니다. 이 인코딩의 PolicyOutput이 아닌 응답(JSON으로 작성되었거나, 형태가 선언하지 않은 최상위 필드를 가진 응답)은 빈 verdict 목록으로 읽히지 않고, 플러그인과 그 export를 명시하며 빌드를 중단합니다. aggrega plugin run-local --export verdict_ir 또는 --export verdict_render로 직접 호출하면, 게스트는 작성된 JSON 페이로드를 이 인코딩으로 변환한 것을 받고, 그 응답은 export의 출력 형태로 읽혀 JSON으로 출력됩니다. 그 형태가 아닌 응답은 빌드가 거부하는 것과 같이 export를 명시하며 거부됩니다.

타입 정의. 정책 와이어 타입은 같은 세 ABI 패키지에 게시됩니다. PolicyInput(ir-verdict 역할), RenderPolicyInput(render-verdict 역할), 공유 PolicySource, 그리고 results 항목이 Diagnostic 값인 PolicyOutput입니다. 진단의 심각도는 모든 소켓이 공유하는 세 값(halt, warn, info) 중 하나이며, 이 세 값은 세 패키지 각각에 와이어 타입과 함께 상수로 게시되므로, 게스트는 호스트가 라우팅하는 것과 같은 닫힌 집합에서 보고합니다. 다른 값을 반환하는 게스트는 플러그인과 반환한 값을 명시한 메시지와 함께 빌드를 중단합니다. 라우팅할 수 없는 심각도는 호스트가 버리는 진단이 아니라 호스트가 보고하는 플러그인 결함입니다.

출력 형태 계약 — FeatureRecipe 파이프라인과 provider 소켓

아래 소켓은 컴파일러가 빌드 시 디스패치하는 타입이 지정된 계약 표면을 지닙니다. FeatureRecipe와 Recipe의 pipeline: 단계는 렌더링된 문서 집합에 대해 플러그인 파이프라인에서 실행되고, provider 렌더링 소켓은 기본 렌더링 시점에 실행되며, publishing-linter는 대역 외에서 실행됩니다.

RFC 6902 패치(플러그인 파이프라인)

플러그인 파이프라인에서 실행되는 FeatureRecipe와 Recipe의 pipeline: 단계는 렌더링된 문서 집합에 대해 RFC 6902 JSON Patch 연산을 내보냅니다. 호스트는 키가 지정된 문서 집합 전체를 각 단계에 넘기고, 단계는 대상 문서를 내용으로 선택하여 키로 주소가 지정된 패치를 반환하며, 적용 엔진이 이를 해당 문서에 적용합니다. 일반적으로 사이드카 컨테이너 추가, 시크릿 볼륨 마운트, 환경 변수 재작성 등이 이에 해당합니다. 단계는 side_effects(아래 참조), diagnostics(각 항목은 모든 소켓이 문제를 보고하는 데 쓰는 공유 Diagnostic 형태와 같음), outputs(아래 참조)도 반환합니다. examples/04-secrets.md에서 설명합니다.

현재 상태: 사용 가능. 선언된 각 단계는 aggrega build 중에 실행됩니다.

와이어 인코딩. 단계의 입력(FRPStepInput)과 응답(FRPStepOutput)은 양방향 모두 정규 CBOR(RFC 8949 §4.2.1)로 전달됩니다. 게스트는 페이로드 타입이 제공하는 진입점을 통해 입력을 디코딩하고 응답을 인코딩합니다. Go에서는 DecodeCBOR와 EncodeCBOR, Rust에서는 decode_cbor와 encode_cbor(aggrega-abi 크레이트가 게시하는 타입에 있음), TypeScript에서는 decodeCBORFRPStepInput와 encodeCBORFRPStepOutput를 사용하며, 바이트를 읽고 씁니다(Rust에서는 Vec<u8>, TypeScript에서는 Host.inputBytes()와 Host.outputBytes(...)). CBOR 라이브러리는 필요하지 않으며 바이트를 직접 파싱하는 곳도 없습니다. 단계의 with 입력(step_input), 반환하는 outputs, 그리고 own과 host 문서 집합은 스키마가 순서 보존으로 표시한 맵이므로, 파이프라인이 보유한 순서대로 순서가 있는 항목 목록으로 전달되고, 게스트는 킷의 순서 유지 컨테이너를 통해 이를 읽고 씁니다. 이 덕분에 단계의 출력이 단계가 반환한 순서대로 .steps.<id>.outputs에 도달합니다. 각 유닛의 tree, step_input과 outputs의 각 값, 패치의 value, 부수 효과의 crd, 렌더 context는 각자의 JSON 문서 바이트로 전달되며, 게스트는 내용을 보려면 이를 JSON으로 파싱합니다. 유닛의 bytes는 생성된 디코더가 킷 고유의 필드 타입(Go에서는 바이트 슬라이스, Rust와 TypeScript에서는 base64 문자열)에 채우는 원시 바이트열로 전달됩니다. 각 진단은 공유 Diagnostic 형태로 전달됩니다. 이 인코딩의 FRPStepOutput가 아닌 응답(JSON으로 작성된 응답이나 형태가 선언하지 않은 최상위 필드를 가진 응답)은 실행하는 함수를 명시하며 단계를 실패시키고, 단계가 optional이 아니면 빌드가 중단됩니다. aggrega plugin run-local --export step으로 직접 호출하면, 단계에는 작성된 JSON 페이로드가 이 인코딩으로 변환되어 전달되고, 응답은 export의 출력 형태로 읽혀 JSON으로 출력됩니다. 그 형태가 아닌 응답은 빌드가 거부하는 것과 같이 export를 명시하며 거부됩니다.

부수 효과 — 리소스 내보내기(플러그인 파이프라인의 자격 증명 플러그인)

자격 증명 FeatureRecipe 파이프라인(Two-Part Plugin Principle: Fetcher + Injector)은 단계의 side_effects를 통해 패치와 함께 완전한 리소스를 내보내며, 각각 계약이 정의하는 두 종류 중 하나를 선언합니다. emit_crd는 클러스터가 런타임에 가져오는 ExternalSecret 또는 VaultSecret CRD 같은 커스텀 리소스 문서이고, emit_file은 기록된 파일입니다. 다른 종류를 반환하는 단계는 노드, 부수 효과의 인덱스, 선언한 종류를 명시하며 빌드를 중단합니다. Fetcher의 단계는 완전한 리소스를 내보내고, Injector의 단계는 그 결과로 생긴 Kubernetes Secret을 마운트하는 패치를 반환합니다. examples/04-secrets.md에서 설명합니다.

현재 상태: 사용 가능.

단계 출력(pipeline: 단계의 outputs 맵)

플러그인 파이프라인 단계는 후속 단계가 {{ .steps.<id>.outputs.<key> }}로 사용하는 이름 있는 출력을 게시합니다. 출력 형태는 플러그인별로 provider가 정의합니다. 단계 출력의 범위는 같은 파이프라인으로 한정되며, 선언 순서상 후속 단계에서만 보입니다. templates/expansion-matrix.md의 10행에 문서화되어 있습니다.

현재 상태: 사용 가능.

Provider 렌더링 — 게스트 주도 소켓

provider는 Wasm 게스트입니다. 렌더링은 Wasm 전용입니다. Recipe의 capability: 이름은 해당 이름을 spec.provider.capabilities에 나열하고 render_node export를 알리는 provider 렌더링 Plugin(pluginType: provider)으로 해석되며, 그 플러그인의 게스트가 노드를 렌더링합니다. 대체로 사용할 호스트 내부 렌더러는 없으며, 서비스하는 Plugin으로 해석되지 않는 provider 이름은 라우팅 시점에 빌드를 중단합니다. 표준 provider를 추가하는 것은 .wasm 게스트와 카탈로그 Plugin 엔티티를 배포하는 것이며, 호스트에는 provider별 코드가 없습니다.

provider가 서비스하는 capability에는 콜론이 없으며, 파이프라인 단계가 호환된다고 선언하는 capability도 마찬가지입니다. Recipe의 capability:는 마지막 콜론까지를 capability로, 그 뒤를 버전 고정으로 읽습니다. helm:1.0.0은 1.0.0 버전의 helm을 요청합니다. 따라서 콜론을 포함한 이름은 어떤 Recipe도 요청할 수 없습니다. 호스트는 provider 또는 pipeline-step 게스트의 describe() capabilities에 있는 그러한 이름을, 게스트가 로드될 때와 게시용 엔티티가 생성될 때 거부하며, 게스트와 이름을 명시합니다. 파서의 parse:<format>와 임포터의 import:<format>는 콜론을 유지합니다. 이들은 형식으로 조회되며 Recipe의 capability:를 통해서는 조회되지 않습니다.

호스트는 범용 라우터입니다. 게스트의 describe() 자체 보고(렌더 동작 계약 포함)를 읽고, 어떤 provider 형식도 이해하지 않은 채 게스트의 export를 디스패치합니다. 이 계약은 데이터로서 디스패치를 구동합니다.

  • input_kinds(sourced, synthesized, artifacts_standalone) — 게스트가 렌더링하는 Recipe 입력 종류입니다. 호스트는 노드의 입력 종류를 이 집합에 비추어 제한합니다.
  • boundary_assembly(none | merge | nest) — 게스트가 디스패치 그룹의 출력을 결합하는 방식입니다. merge는 노드별 출력을 어셈블러가 하나의 아티팩트로 병합하는 조각으로 분류하고, nest는 노드별 파일을 조립된 래퍼 아래에 중첩하며, none은 각 노드의 출력을 직접 기록합니다.
  • nest_segment(선택 사항) — nest 어셈블리에서 각 기여자의 하위 디렉터리를 두는 디렉터리로, 하나의 디렉터리 이름으로 작성합니다. 없으면 각 기여자의 하위 디렉터리는 디스패치 위치에 바로 놓입니다.
  • assembly_name_annotation(선택 사항) — 해석된 값이 게스트가 디스패치 그룹으로부터 조립하는 아티팩트의 이름이 되는 경계 어노테이션입니다. 없으면 게스트는 디스패치 경로만으로 어셈블리의 이름을 정합니다.
  • cross_boundary_linking(선택 사항) — 게스트가 경계를 넘는 uses 엣지를 link_publish와 link_resolve export를 통해 연결하는지 여부입니다. 게스트는 둘 다 export할 때에만 이를 true로 선언하며, 플래그와 export가 일치하지 않는 게스트는 로드 시 거부됩니다.
  • artifact_delimiters(선택) — 게스트가 아티팩트 본문에 적용하는 Go 템플릿 구분자 쌍입니다.
  • reusable_instance(선택) — 로드된 인스턴스 하나가 빌드의 모든 호출을 처리할 수 있는지 여부입니다(아래 결정성과 인스턴스 재사용 참조).
  • omits(선택) — 게스트가 소스 렌더에 포함된 생략 항목을 준수하는지 여부입니다(아래 렌더링된 유닛 제외하기 참조).
  • boundary_artifacts(선택) — 게스트의 대상이 Recipe가 경계의 공유 출력에 기여하는 파일을 수용하는지 여부입니다(아래 Recipe가 경계에 기여하는 파일 수용하기 참조).
  • source_ignore(선택) — 게스트의 생태계가 렌더링하는 소스 옆에 결코 함께 배포하지 않는 파일입니다(아래 소스의 생태계가 배포하지 않는 것 선언하기 참조).

이 소켓은 고정된 export 집합입니다. 하나는 필수이고, 나머지는 선택이며 describe()에서 알립니다.

  • render_node(필수) — IR 노드 하나를 provider 고유 파일로 렌더링합니다.
  • assemble_boundary(선택) — 디스패치 그룹의 노드별 출력을 경로당 하나의 아티팩트로 병합합니다(boundary_assembly가 merge 또는 nest일 때 존재).
  • validate_node_input(선택) — 노드 입력에 대한 렌더 전 구조 검증입니다. halt 진단은 빌드를 중단하고, warn은 빌드 결과에 표시됩니다.
  • carve / reassemble(선택, 쌍) — 렌더 후 파이프라인 단계를 위한 게스트 고유의 바이트 충실 패치 코덱으로, 둘 다 알려진 경우에만 사용됩니다.
  • name_bound(선택) — 호스트가 컴포넌트 식별자로 제안하는 이름이 대상이 허용하는 이름을 만들어 내는지 게스트가 판단하며, 자체 이름 대신 제약 조건으로 응답합니다.
  • rendered_name(선택) — 게스트가 노드에 대해 렌더링하는 리소스에 대상이 부여하는 이름을 보고합니다.
  • link_publish / link_resolve(선택, 쌍) — 게스트가 경계를 넘는 uses 엣지를 연결합니다. 소비되는 엔드포인트가 핸들을 게시하고, 소비하는 엔드포인트가 이를 자신의 조립된 출력 안으로 해석합니다.

Recipe의 artifacts:는 입력의 아티팩트 프로젝션을 통해 render_node에 합쳐집니다. 호스트가 $import 읽기, Go 템플릿 평가, 출처 키/값 계산을 수행하고 각 항목을 이미 읽고 평가한 상태로 게스트에 전달합니다. 게스트는 자신만 아는 형식으로 배치와 출력을 담당합니다. architecture/13-catalog-and-registry.md에 문서화되어 있습니다.

소스 렌더의 입력은 노드의 값을 node.values에 담고, node.values_mapped는 그 값의 출처를 알려 줍니다. 값이 Recipe의 valuesMapping(첨부의 자체 렌더라면 그 FeatureRecipe의 것)의 출력이면 true이고, 컴포넌트 자체의 값이 작성된 그대로 전달되면 없습니다. 게스트가 이를 읽는지는 해당 게스트 자체의 계약입니다. cloudformation 프로바이더는 소스 템플릿의 Parameters를 매핑이 생성한 값에서만 바인딩하는데, 컴포넌트 자체의 값은 Recipe의 다른 입력을 위해 작성되었을 수 있기 때문입니다. terraform 프로바이더는 소스 모듈의 인수를 조립이 받는 값으로 작성하며 이 플래그를 읽지 않습니다. 이 값들은 소스에서 렌더링된 노드에 대해 assemble_boundary 입력의 각 렌더링된 노드에 실려 전달됩니다. 컴포넌트의 값은 매핑이 생성했는지와 관계없이, 첨부된 Feature의 값은 그 FeatureRecipe의 valuesMapping이 생성한 경우에만 전달됩니다. 같은 플래그가 그 옆에, 값이 전달되는 곳에서만 함께 전달되므로 어셈블러는 노드 자체의 렌더와 같은 답을 읽습니다. cloudformation 프로바이더는 거기서 이를 읽어 노드의 바인딩이 채운 파라미터를 파악하고, 첨부된 Feature의 호스트를 포함해 스택의 다른 곳에서 그 파라미터를 참조하는 것을 거부합니다. 이 플래그는 값이 생성된 방식을 기록하며 키나 값에서 도출되지 않습니다.

와이어 인코딩. 이 소켓의 모든 익스포트는 입력을 받고 출력을 반환할 때 양방향 모두 정규 CBOR(RFC 8949 §4.2.1)를 사용합니다. 게스트는 페이로드 타입이 이미 제공하는 진입점을 통해 입력을 디코딩하고 출력을 인코딩합니다. Go에서는 DecodeCBOR와 EncodeCBOR, Rust에서는 decode_cbor와 encode_cbor, TypeScript에서는 각 타입의 decodeCBOR 및 encodeCBOR 함수(예: decodeCBORRenderNodeInput와 encodeCBORRenderNodeOutput)이며, 바이트를 읽고 씁니다(Rust에서는 Vec<u8>, TypeScript에서는 Host.inputBytes()와 Host.outputBytes(...)). CBOR 라이브러리가 필요 없고 바이트를 직접 파싱하는 일도 없습니다. 렌더링된 파일의 content를 비롯한 모든 바이트 필드는 원시 바이트열로 전달되며, 생성된 디코더가 이를 킷 자체의 필드 타입에 채웁니다. Go에서는 바이트 슬라이스, Rust와 TypeScript에서는 base64 문자열입니다. 스키마가 순서 유지로 표시한 맵(노드의 values, features, uses, 응답의 derived_keys, 조립 기여자의 values 등)은 빌드가 보유한 순서대로 항목의 순서 있는 목록으로 전달되며, 게스트는 킷의 순서 유지 컨테이너를 통해 이를 읽습니다. 노드 values의 각 값은 자체 JSON 문서의 바이트로 전달되므로 값 내부의 키는 작성된 순서를 유지합니다. features의 각 첨부 항목, 렌더 컨텍스트, 파싱된 워크로드, 각 보강된 엣지, 각 분할된 유닛, 각 패치 연산도 마찬가지이며, 게스트는 내부를 보려면 이를 JSON으로 파싱합니다. 각 진단은 공유 Diagnostic 형태로 전달됩니다. 이 인코딩으로 된 익스포트의 출력 형태가 아닌 응답(JSON으로 작성된 응답, 또는 형태가 선언하지 않은 최상위 필드를 가진 응답)은 호출한 익스포트를 명시하며 빌드를 중단합니다. 이 페이지의 페이로드 예시는 읽기 쉽도록 JSON으로 작성되어 있습니다. aggrega plugin run-local --export render_node이나 이 소켓의 다른 익스포트로 직접 호출하면, 게스트는 작성된 JSON 페이로드를 이 인코딩으로 변환한 것을 받고, 그 응답은 익스포트의 출력 형태로 읽혀 JSON으로 출력됩니다. 그 형태가 아닌 응답은 빌드가 거부하는 것과 마찬가지로 익스포트를 명시하며 거부됩니다.

현재 상태: 다섯 프로바이더 모두 사용 가능. helm 게스트는 소스 차트(차트 루트 해석), 합성된 워크로드, 독립 아티팩트를 평면 Kubernetes 매니페스트로 렌더링합니다. helm-chart 게스트는 각 노드의 소스 차트를 서브 차트로 중첩하여 엄브렐라 차트를 조립하며, 바이트 충실 패치 코덱과 대괄호([[ ]]) 아티팩트 구분자를 갖추고 있습니다. compose 게스트는 소스 compose 파일과 합성된 워크로드를 렌더링하고 디스패치 그룹을 하나의 docker-compose.yaml로 병합하며, 서비스를 그 x-aggrega-networks-of가 지정하는 컴포넌트의 네트워크에 연결합니다. terraform 게스트는 Terraform 구성을 그대로(HCL 또는 JSON) 출력하거나 소스 모듈을 벤더링하고 그 입력을 해당 컴포넌트의 모듈 블록 인수로 제공하며, 렌더 전에 소스 모듈의 HCL을 구조적으로 검증하고, 경계를 각 컴포넌트를 해당 컴포넌트 자체의 하위 디렉터리를 소스로 하는 모듈 블록으로 선언하는 하나의 루트 구성으로 구성합니다. cloudformation 게스트는 소스 템플릿과 독립 스택 조각을 렌더링하고, 디스패치 그룹을 하나의 스택 템플릿으로 병합하며, 경계를 넘는 uses 엣지를 link_publish와 link_resolve를 통해 연결합니다. 각 게스트는 오프라인에서 결정적으로 렌더링합니다.

게스트가 파생하는 이름 선언하기

프로바이더 게스트는 보통 출력에 필요하지만 아무도 작성하지 않은 이름, 즉 대상이 하나의 리소스를 지칭하는 식별자나 다른 쪽이 참조하도록 하나의 출력을 게시하는 이름을 노드 정체성과 내보내는 리소스로부터 파생합니다. 두 노드는 파생의 기반이 되는 부분이 일치할 때마다 같은 이름에 도달할 수 있으며, 그 이름은 호스트가 그대로 기록하는 파일 바이트 안에 있으므로 호스트는 충돌을 볼 수 없습니다. 충돌을 찾으려면 프로바이더의 형식을 파싱해야 하는데, 그것이 바로 게스트에 머무는 지식입니다.

따라서 render_node는 출력에 선택적 derived_keys를 반환하며, 방향은 반대가 됩니다. 호스트가 출력을 검사하는 대신 게스트가 선언하고 호스트가 확인합니다:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"derived_keys": {
"logical-ids": ["paymentsapiQueue", "paymentsapiTopic"],
"export-names": ["aggrega--prod--api--orders-db--host"]
}
}

derived_keys의 각 키는 게스트가 이름 붙이는 키 공간이며, 각 공간은 게스트가 그 안으로 파생한 이름들을 파생 순서대로 담습니다. 공간 이름과 그 안의 이름은 모두 여러분의 어휘입니다. 호스트는 이를 하나의 공간 안에서 동등성을 비교할 문자열로만 읽습니다. 호스트는 이름을 파싱하지 않고, 공간이나 이름이 무엇을 뜻하는지 알지 못하며, 스스로 이름을 파생하지도 않습니다. 따라서 하나의 검사가 모든 프로바이더가 파생하는 모든 종류의 이름을 다루며, 새 프로바이더에는 새 호스트 코드가 필요하지 않습니다. 게시된 타입에서 derived_keys는 순서를 유지하는 맵이므로, 공간은 게스트가 설정한 순서대로 전달됩니다.

호스트가 이 이름들로 하는 일은 단 하나의 질문입니다. 하나의 공간 안에서, 출력이 하나의 어셈블리로 병합되는 기여자들 사이에 선언된 모든 이름이 서로 다른가? 두 기여자가 하나의 공간에서 같은 이름을 선언하면 빌드가 중단되며, 중단 메시지는 공간, 이름, 두 기여자를 모두 명시하므로 작성자는 프로바이더를 읽지 않고도 조치할 수 있습니다. 서로 다른 이름, 그리고 서로 다른 두 공간에서 우연히 일치하는 이름은 통과합니다.

무엇을 선언할지 정할 때 알아 둘 만한 세 가지 속성이 있습니다:

  • 범위는 하나의 어셈블된 출력입니다 — 파일이 함께 병합되는 기여자들의 집합입니다. 그보다 좁거나 넓은 범위에서 고유성을 원하는 게스트는 선언하는 공간 이름에 그 범위를 표현하며, 이로써 선택은 호스트가 아니라 여러분의 몫으로 남습니다.
  • 하나의 기여자는 이름을 자유롭게 반복할 수 있습니다. 노드는 소스 렌더, 워크로드 합성, 아티팩트 배치 등 여러 크로싱에 걸쳐 렌더링될 수 있으며, 선언은 병합됩니다. 한 기여자가 같은 이름을 두 번 선언하는 것은 그 기여자가 하나의 리소스를 두 번 기술하는 것이지 충돌이 아닙니다.
  • 선언은 바이트를 바꾸지 않습니다. 이 필드는 게스트가 파생한 것에 대한 단언이지 내보낸 것에 대한 변경이 아니므로, 게스트의 렌더링된 출력은 선언 여부와 관계없이 동일합니다. derived_keys를 생략하는 것은 유효하며, 해당 게스트에 대해서는 검사가 작동하지 않습니다.

게스트가 내보낸 것에 대한 사실 보고하기

노드 렌더에 관한 어떤 것들은 그것을 생성한 프로바이더에게만 보입니다. 작성한 문서에 무엇이 들어 있는지, 어떤 이름을 정의하는지, 무언가를 몇 개 내보냈는지 등이 그렇습니다. 파일 바이트에서 이를 읽어 내려면 프로바이더의 형식을 이해해야 하기 때문입니다. render_node는 이러한 것을 파일 옆의 선택적 render_facts 목록에 직접 보고할 수 있습니다:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"render_facts": [
{ "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] },
{ "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] }
]
}

각 사실은 name과 value이며, 둘 다 여러분의 프로바이더에 속합니다. 어떤 사실을 보고하는지, 각 이름이 무엇을 뜻하는지, 각 항목이 무엇을 담는지는 프로바이더 자체의 문서화된 계약의 일부이므로, 이를 읽을 작성자를 위해 문서화하십시오.

항목이 하나뿐이더라도 모든 사실의 값은 목록, 즉 JSON 배열로 보고하십시오. 하나의 이름은 컴포넌트의 여러 렌더에서 보고될 수 있습니다. 컴포넌트 자체의 렌더가 차트 렌더와 아티팩트 배치처럼 여러 호출로 이루어질 수 있고, 컴포넌트에 연결된 각 Feature는 자체 프로바이더 호출을 통해 렌더링됩니다. 어떤 프로바이더도 렌더링 시점에 자신의 보고가 한 이름 아래 유일한 보고가 될지 알 수 없으므로 모든 보고는 목록이며, 컴파일러는 한 이름이 받은 목록들을 하나의 목록으로 합칩니다. 값이 객체, 문자열, 숫자, 불리언, null 등 다른 것인 사실은 게스트가 반환할 때 거부됩니다. 빌드는 짧은 코드 E0325로 중단되며, 사실, 노드, 게스트를 명시하고 값이 무엇이었는지 알려 줍니다. 목록 안의 항목은 여러분이 문서화한 형태의 어떤 JSON 값이든 될 수 있습니다.

값이 목록이라는 것이 컴파일러가 그 값에 대해 아는 유일한 사실입니다. 컴파일러는 사실을 이름으로 키를 지정하고 각 목록을 그것을 읽는 템플릿에 넘깁니다. 호스트 컴포넌트의 사실은 그에 연결된 모든 Feature에, 각 호출자의 사실은 호출자의 렌더 사실을 읽는다고 선언한 Feature에, 각 대상의 사실은 호스트가 연결된 컴포넌트의 렌더 사실을 읽는다고 선언한 Feature에 넘기며, 이는 템플릿 컨텍스트에서 설명하는 대로입니다. 이때 각 목록은 템플릿이 range로 순회할 수 있는 값으로 디코딩됩니다. 컴파일러는 이름이나 항목이 무엇을 뜻하는지 알지 못하고 스스로 사실을 파생하지도 않으므로, 새 프로바이더는 컴파일러 쪽의 아무런 변경 없이 새 사실을 보고할 수 있습니다. 노드에 연결된 Feature가 자체 렌더에서 보고한 사실은 노드 자체 렌더가 보고한 사실과 분리되어 유지됩니다.

무엇을 보고할지 정할 때 알아 둘 만한 네 가지 속성이 있습니다:

  • 순서는 여러분의 몫입니다. 사실은 게스트가 나열한 순서를 유지하고, 각 값은 자체 바이트를 유지합니다. 목록 항목의 순서와 각 객체 키의 순서는 게스트가 작성한 순서입니다. 동일한 입력이 동일한 바이트를 생성하도록 사실을 고정된 순서로 나열하고 각 항목을 고정된 키 순서로 작성하십시오. 맵이 아닌 사실 목록을 쓰는 이유는 바로 그 순서가 아무것도 표시하지 않아도 모든 키트의 자체 시퀀스 타입에서 유지되도록 하기 위해서입니다. 맵은 스키마가 순서 보존으로 표시하고 게스트가 키트의 순서를 유지하는 컨테이너를 채울 때에만 게스트가 작성한 순서를 유지합니다.
  • 보고는 바이트를 바꾸지 않습니다. 컴파일러가 기록하는 파일은 사실이 함께 오든 그렇지 않든 게스트가 반환한 파일입니다.
  • 노드는 여러 크로싱에 걸쳐 보고할 수 있습니다. 노드는 소스 렌더, 워크로드 합성, 아티팩트 배치로 렌더링될 수 있습니다. 각각이 보고한 사실은 크로싱이 실행된 순서대로 유지되며, 둘 이상에서 보고된 이름은 그 순서대로 합친 하나의 목록으로 읽힙니다.
  • 아무것도 보고하지 않아도 완전합니다. render_facts를 생략하는 것은 유효하며, 아무것도 보고하지 않는 프로바이더는 이 필드가 없을 때와 정확히 똑같이 렌더링합니다.

RenderFact 타입은 세 ABI 패키지에 게시되어 있고 각 언어의 플러그인 개발 키트에서 다시 내보내지며, 키트의 렌더 예제는 파일 옆에 두 개의 사실을 보고합니다. Go에서 값은 게스트가 작성하는 JSON입니다. 맵이 아닌 구조체 슬라이스를 마샬링하는 것이 각 항목의 키를 선언한 순서대로 유지하는 방법입니다:

type stackFact struct {
Name string `json:"name"`
Resources int `json:"resources"`
}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})
if err != nil {
pdk.SetError(err)
return 1
}
out := aggrega.RenderNodeOutput{
Files: files,
RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},
}

렌더링된 단위 제외하기

소스 렌더는 provider가 렌더링 결과에서 제외해야 하는 단위를 지정할 수 있습니다. 예를 들어 가져온 차트가 렌더링할 때마다 새로 생성하는 Secret이 그렇습니다. 항목이 어떤 렌더링된 단위를 가리키는지는 provider만 아는 지식이므로, 항목은 게스트로 전달되고 제외 작업은 게스트가 수행합니다. 항목은 render_node의 입력에서 source_listing 옆에 선택적 omits 목록으로 도착합니다:

{
"node": { "id": "payments-api" },
"context": { },
"source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] },
"omits": [
{ "kind": "Secret", "name": "payments-api-token", "namespace": "payments" },
{ "kind": "ConfigMap", "name": "payments-api-dashboards" }
]
}

각 항목은 kind, name, 선택적 namespace로 이루어지며, 이미 일반 문자열로 해석되어 작성자가 선언한 순서대로 나열됩니다. 빌드에 적용되지 않는 항목은 전달되지 않습니다. 세 필드가 무엇을 선택하는지는 provider 자체의 계약, 즉 대상 형식에서 리소스의 kind, name, namespace이므로, 항목을 작성하는 작성자를 위해 이를 문서화하십시오.

작성자는 민감하다고 선언한 값으로 항목의 필드를 구성할 수 있습니다. 예를 들어 민감한 설정의 이름을 딴 리소스가 그렇습니다. 이러한 항목은 "sensitive": true와 함께 도착하며, 게스트는 렌더 입력이 담고 있는 다른 모든 표시된 값과 동일하게 이를 취급합니다(Values an input marks sensitive 참조). 즉, 항목의 용도대로 필드로 항목을 계속 일치시키고 개수를 세되, 거부, 경고 또는 로그 줄에는 어떤 필드도 포함하지 않습니다. 컴파일러는 어느 필드가 해당 값에서 생성되었는지 알려 주지 않으므로 표시는 항목 전체에 적용됩니다. 이러한 값으로 구성된 필드가 없으면 표시는 없습니다.

항목을 준수하는 게스트는 세 가지를 수행합니다:

  • 모든 항목을 렌더링한 결과와 대조합니다. 대조는 해당 형식의 용어로 이루어집니다.
  • 일치한 각 단위를 반환하는 모든 것에서 제외합니다. 여기에는 files, derived_keys에 선언하는 이름, render_facts에 보고하는 사실이 포함되므로, 컴파일러가 받는 어떤 것도 해당 단위를 여전히 설명하지 않습니다.
  • 항목마다 하나의 개수를 보고합니다. 개수는 출력의 선택적 omitted 목록에 항목이 도착한 순서대로 담기며, 각각은 해당 항목이 일치한 단위의 수로, 다른 항목도 그 단위와 일치했는지와 관계없이 셉니다:
{
"files": [ { "path": "templates/deployment.yaml", "content": "..." } ],
"omitted": [1, 0]
}

0도 완전한 답입니다. 해당 항목이 게스트가 렌더링한 어떤 것과도 일치하지 않았다는 뜻입니다. 제외된 것에 관해 되돌아오는 것은 개수뿐이며, 단위 자체는 게스트가 반환한 것에 단순히 존재하지 않습니다.

세 가지를 모두 수행하는 provider는 계약에 omits: true로 이를 선언합니다. Plugin 엔터티는 같은 주장을 spec.provider.contract.omits로 기록합니다. 엔터티가 렌더 동작 계약을 담고 있으면, 로드 시 describe()가 다른 값을 보고하는 게스트를 거부합니다. 항목은 소스 목록에만 동반됩니다. 합성된 workload나 아티팩트 집합의 렌더에는 항목이 전달되지 않습니다.

항목이 없는 렌더는 이 필드들의 영향을 받지 않습니다. 두 필드 모두 선택 사항이며 비어 있으면 존재하지 않으므로, 항목이 없는 렌더는 필드가 존재하지 않는 경우와 바이트 단위로 동일하게 소켓을 통과하고, 필드를 읽지 않는 게스트는 영향을 받지 않습니다. OmitEntry 타입은 세 ABI 패키지에 게시되며 각 언어의 플러그인 개발 키트가 다시 내보냅니다.

컴파일러가 답을 처리하는 방식. 항목은 작성자가 Recipe 또는 FeatureRecipe에 작성하는 omits: 키에서 옵니다(Recipe → The omits: field). 컴파일러는 각 항목의 템플릿을 평가하고 적용되는 항목을 게스트에 넘깁니다. 그런 다음 개수를, 오직 개수만 읽으며, 이를 확인하려고 반환된 파일을 들여다보지 않습니다:

  • 넘긴 항목마다 음이 아닌 개수 하나가 아닌 개수 목록은 빌드를 중단합니다. 목록이 없거나, 너무 짧거나, 너무 길거나, 0 미만의 개수를 담은 경우이며, 노드, provider, 넘어간 항목 수와 되돌아온 개수의 수를 명시합니다. 맞지 않는 보고로는 어느 항목이 무엇을 제외했는지 알 방법이 없습니다. A provider’s omitted counts do not match the omits entries it was handed (provider의 omitted 개수가 전달받은 omits 항목과 일치하지 않음)를 참조하십시오.
  • 0은 빌드를 중단합니다. 작성자 순서에서 개수가 0인 첫 번째 항목을 명시하며, 노드, provider, 해당 문서가 선언하는 목록에서 항목의 위치, 그리고 항목이 해석된 kind, name, namespace를 알려 줍니다. 0을 보고하는 것은 게스트이고, 중단은 컴파일러가 합니다. An omits entry left out nothing the source rendered (omits 항목이 소스가 렌더링한 것을 아무것도 제외하지 않음)를 참조하십시오.
  • omits:를 선언하는 문서의 provider가 omits: true를 주장하지 않으면 렌더링 전에 거부됩니다. 따라서 작성자는 출력에서 문서를 발견하는 대신 키가 아무 효과가 없었을 것임을 즉시 알게 됩니다. 컴파일러는 빌드의 모든 Recipe와 FeatureRecipe가 바인딩되면 describe()에서 주장을 읽고, 첫 component가 렌더링되기 전에 거부합니다. 따라서 키를 주장하지 않는 게스트는 항목을 받지 않습니다. 거부 시 provider와 문서가 렌더링되는 component를 명시하며, 경계에 대해 한 번 생성하는 FeatureRecipe의 경우 경계와 첨부를 명시합니다. The provider does not support omits (provider가 omits를 지원하지 않음)를 참조하십시오.

현재 상태: 사용 가능. 컴파일러와 함께 배포되는 helm, compose, cloudformation 게스트는 주장을 선언하고 항목을 준수합니다. helm 게스트는 반환하는 텍스트에 어떤 항목의 필드도 쓰지 않습니다. compose와 cloudformation 게스트는 항목을 거부할 때 항목의 kind, name, namespace를 명시하고, 제외된 단위를 여전히 가리키는 파일이나 템플릿을 거부할 때 해당 항목이 제외한 단위를 명시하며, 그 자리에서 표시된 항목의 모든 필드를 <redacted>로 표시합니다. helm-chart와 terraform 게스트는 주장을 선언하지 않으므로, 이들 중 하나가 렌더링하는 omits: 선언 문서는 거부됩니다.

Recipe가 경계에 기여하는 파일 수용하기

일부 파일은 경계의 component 하나가 아니라 경계 전체에 속합니다. 예를 들어 대상이 경계가 배포하는 모든 것에 대해 한 번 읽는 provider 구성이 그렇습니다. Recipe는 이러한 파일을 spec.boundary.artifacts 아래에 작성하며, 작업은 게스트가 아니라 컴파일러가 수행합니다. 컴파일러는 각 파일을 artifacts: 항목이 평가되는 컨텍스트에 대해 평가하고, 디스패치 그룹의 모든 기여자가 선언한 파일을 이름별로 병합하며, 그룹의 조립된 출력을 담는 디렉터리에 assemble_boundary가 반환하는 것과 나란히 각 파일을 한 번 씁니다. 게스트는 어떤 export에서도 이 파일을 받지 않고 이에 관해 질문받지도 않으므로 구현할 것은 없으며, 대상에 관한 진술만 하면 됩니다:

"contract": {
"input_kinds": { "sourced": true, "artifacts_standalone": true },
"boundary_assembly": "nest",
"boundary_artifacts": true
}

대상이 해당 디렉터리에 놓인 파일을 경계 출력의 일부로 읽는 경우에만 boundary_artifacts: true를 선언하십시오. Plugin 엔터티는 같은 주장을 spec.provider.contract.boundaryArtifacts로 기록합니다. 엔터티가 렌더 동작 계약을 담고 있으면, 로드 시 describe()가 다른 값을 보고하는 게스트를 거부합니다. 블록을 선언하는 Recipe의 provider가 이를 주장하지 않으면 렌더링 전에 거부되며, provider와 component를 명시합니다. The provider does not support boundary artifacts (provider가 boundary artifacts를 지원하지 않음)를 참조하십시오. 이러한 병합이 조립 결과도 쓰는 이름 아래에 파일을 놓으면 two contributors writing one output path (두 기여자가 같은 출력 경로에 씀)로 빌드가 중단되므로, 조립 결과가 쓰는 이름은 작성자를 위해 문서화해야 할 내용의 일부입니다.

현재 상태: 사용 가능. 컴파일러와 함께 배포되는 terraform 게스트는 주장을 선언하며, Terraform은 경계의 루트 구성 옆에 있는 각 파일을 읽습니다. helm, compose, helm-chart, cloudformation 게스트는 이를 선언하지 않습니다.

소스의 생태계가 절대 배포하지 않는 것 선언하기

Recipe의 로컬 소스 디렉터리(함께 위치한 차트, 모듈)는 Recipe와 함께 게시되며, 그 안의 모든 파일이 Recipe에 속하는 것은 아닙니다. 프로바이더 게스트는 자신의 생태계가 절대 배포하지 않는 것을 계약의 source_ignore를 통해 .gitignore가 사용하는 구문의 무시 규칙으로 선언합니다:

"contract": {
"input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false },
"boundary_assembly": "none",
"source_ignore": {
"patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"],
"files": [".helmignore"]
}
}
  • patterns는 소스 디렉터리의 루트에서 읽는 규칙으로, 순서대로 적용되며 나중에 일치한 규칙이 앞서 일치한 규칙을 덮어씁니다.
  • files는 생태계가 소스 내부에서 따르는 무시 파일의 이름을 지정합니다. 소스를 탐색하다가 이런 파일을 만나면, 그 줄들은 패턴 다음에 해당 파일을 담은 디렉터리에 대한 추가 규칙으로 읽힙니다.

선언은 엔티티가 렌더링될 때가 아니라 고정(pin)될 때 읽힙니다. 작성자의 pin 단계는 작성자의 워크스페이스에서 엔티티의 capability를 제공하는 플러그인을 확인하고, 플러그인의 규칙을 작성자 자신의 .aggregaignore(이 파일의 줄은 마지막에 오므로 자신이 지정하는 모든 경로에서 우선합니다)와 합성한 뒤, 플러그인의 이름을 버전 없이, 합성된 정확한 규칙과 함께 엔티티의 entity.lock에 기록합니다. 이후 해당 엔티티의 모든 게시, 비교, 렌더링은 기록된 규칙을 적용하며, 호스트는 그 규칙을 매칭할 뿐 어떤 생태계에 대해서도 자체 견해를 갖지 않습니다. 따라서 렌더링 시 게스트가 전달받는 파일(목록, 그리고 게스트가 호스트에 pack 또는 read를 요청하는 모든 파일)은 정확히 엔티티의 게시본이 담는 파일이며, 규칙이 제외한 파일은 해당 파일을 명시하며 존재하지 않는 것으로 응답됩니다. 소스 아래의 심볼릭 링크는 게스트가 호출되기 전에 거부됩니다.

호환성은 기록된 내용에서 도출됩니다. 게스트는 같은 ABI 버전을 사용하고, 계약이 엔티티의 주장과 일치하며, 게시된 집합 밖의 파일을 필요로 하지 않을 때 자신의 capability용으로 게시된 Recipe를 렌더링할 수 있습니다. 집합에서 제외된 파일이 필요한 게스트는 빌드를 명시적으로 실패시키고 해당 파일을 명시해야 합니다. 호스트의 pack 또는 read 거부가 그 파일을 명시하며, 게스트는 이를 자신의 실패에 담습니다. 소비자의 워크스페이스가 capability에 바인딩하는 플러그인이 엔티티의 lock에 기록된 것과 다른 규칙을 선언하면, 소비자의 pull은 두 플러그인과 그 차이를 명시하는 경고를 출력하며, 이로 인해 중단되지는 않습니다.

source_ignore를 생략하면 아무 규칙도 선언하지 않으며, 렌더링하는 소스는 작성자 자신의 규칙이 유지하는 모든 파일을 유지합니다. 이 필드는 선택 사항이며 별도의 ABI 버전이 필요하지 않습니다. 이를 생략한 게스트는 아무것도 선언하지 않은 게스트로 로드됩니다. Plugin 엔티티는 같은 선언을 spec.provider.contract.sourceIgnore로 기록하며, 기록한 경우 로드는 describe()가 다른 내용을 보고하는 게스트를 거부합니다.

결정성과 인스턴스 재사용

호스트는 게스트의 출력 바이트를 그대로 사용하므로, 게스트는 동일한 입력에서 동일한 출력을 생성해야 합니다. 기본적으로 게스트는 노드마다 새로 로드되므로, 구조상 노드 간에 전달되는 상태가 없습니다. reusable_instance를 스스로 선언한 게스트는 대신 빌드당 한 번 로드되고 단일 인스턴스가 모든 호출을 처리하므로, 노드별 인스턴스화라는 주된 비용을 줄일 수 있습니다. 재사용은 상태가 없는 게스트에서만 안전하므로, aggrega build --verify-determinism은 각 노드를 같은 인스턴스로 두 번 렌더링하고 어느 노드든 두 렌더링 결과가 다르면 빌드를 중단합니다. 기본 빌드는 한 번만 렌더링하고 선언을 신뢰합니다. Wasm 컴파일 캐시는 디스크 기반이며 프로세스 전역이므로, 게스트는 한 번만 컴파일되고 웜 빌드는 재컴파일을 건너뜁니다.

린터 소켓 — 게시 린터

린터 소켓은 표준 publishing-linter로 제공되며, 이는 컴파일 시점이 아니라 aggrega lint를 통해 실행되는 대역 외 게이트입니다. 카탈로그 엔티티(그리고 --pre-publish 모드에서는 해당 엔티티의 현재 게시된 버전)를 받아, 각각 심각도와 메시지를 가진 검사 결과 목록을 반환합니다. --pre-publish 모드에서는 버전 증가 분류도 반환합니다. 호스트는 다른 모든 소켓과 같은 AOT 순수성 방화벽 뒤에서 내장 Wasm 런타임을 통해 이를 디스패치합니다. 전체 규칙 집합, 심각도, 규칙별 옵트아웃은 cli/aggrega-lint.md에 문서화되어 있습니다.

린터는 선택적으로 적용하는 카탈로그 규율입니다. 컴파일러는 aggrega build 중에 린터를 실행하지 않습니다(유일한 예외는 x-aggrega-* 사용 자제 권고로, 빌드 중에는 warn 심각도로, aggrega lint --pre-publish에서는 halt 심각도로 표시됩니다). 규칙이 플러그인에 있으므로, 기업은 aggrega lint가 다른 린터 플러그인을 가리키게 하여 자체 규율을 적용할 수 있습니다.

aggrega lint가 실행되는 어떤 범위에서도 파라미터 값은 린터 플러그인에 도달하지 않습니다. 문서를 전달하기 전에 호스트는 Aggregate의 파라미터 기본값, Aggregate가 가져오는 각 모듈에 전달하는 값, Release의 파라미터를 보류하고, 각 파라미터 선언의 계약(모든 중첩 수준에서 선언에 쓰인 키만)과 파라미터를 읽는 모든 템플릿 텍스트는 유지합니다. 파라미터의 값 자체가 자격 증명일 수 있고, 여기에 연결된 플러그인은 워크스페이스가 작성하지 않은 코드일 수 있기 때문입니다. 각 문서가 담는 내용은 What a linter plugin is handed(린터 플러그인이 전달받는 것)에 설명되어 있습니다.

와이어 인코딩. 입력과 출력은 모두 정규 CBOR(RFC 8949 §4.2.1)로 전달됩니다. 게스트는 키트의 LinterInput과 LinterOutput이 이미 제공하는 진입점(Go에서는 DecodeCBOR와 EncodeCBOR, Rust에서는 decode_cbor와 encode_cbor, TypeScript에서는 decodeCBORLinterInput과 encodeCBORLinterOutput)을 통해 입력을 디코딩하고 출력을 인코딩하며, 바이트를 읽고 씁니다(Rust에서는 Vec<u8>, TypeScript에서는 Host.inputBytes()와 Host.outputBytes(...)). CBOR 라이브러리는 필요 없으며 바이트를 직접 파싱하지도 않습니다. 엔티티 문서(proposed, previous, implemented_component, release)와 components의 각 값은 해당 JSON 문서의 바이트로 전달되므로, 게스트는 내부를 보려면 이를 JSON으로 파싱합니다. components는 스키마가 순서 보존으로 표시한 맵이므로, Release 전체를 읽는 규칙의 입력에서는 Aggregate가 컴포넌트 인스턴스를 선언한 순서의 순서 있는 항목 목록으로 전달되며, 게스트는 키트의 순서 유지 컨테이너를 통해 이를 읽습니다. policies는 설정된 플래그만 담은 맵으로 전달되므로 담기지 않은 플래그는 false로 읽히며, 각 검사 결과는 공유 Diagnostic 형태로 전달됩니다. 이 인코딩의 LinterOutput이 아닌 응답(JSON으로 작성된 응답이나, 형태가 선언하지 않은 최상위 필드를 담은 응답)은 아무것도 찾지 못한 실행으로 읽히지 않고, 호출한 export를 명시하며 lint를 실패시킵니다. aggrega plugin run-local --export lint_rules로 직접 호출하면, 린터는 작성된 JSON 페이로드를 이 인코딩으로 변환한 것을 전달받고, 그 응답은 export의 출력 형태로 읽혀 JSON으로 출력됩니다. 그 형태가 아닌 응답은 빌드가 거부하는 것과 마찬가지로 export를 명시하며 거부됩니다.

현재 상태: 사용 가능. publishing-linter는 제공되며 aggrega lint를 통해 호스트에서 실행됩니다.

파서 소켓 — 정규 트리 출력

파서는 컴파일러가 기본적으로 읽지 않는 형식으로 작성된 소스를 정규 구조화 트리로 변환하므로, 소비자는 자체 파서를 갖추지 않고 트리를 읽습니다. 호스트는 요청된 형식을 parse:<format>으로 알리는 파서를 확인하고, 세 곳에서 그 파서의 parse export를 호출합니다. 렌더 판정 정책이 기본적으로 읽지 않는 형식의 렌더링된 아티팩트를 받을 때, 임포터가 aggrega_parse_source를 통해 호스트에 트리를 요청할 때, 그리고 형식을 지정하지 않은 가져오기의 형식을 인식할 때입니다(아래의 임포터 소켓 참조). 게스트는 파서를 직접 호출하지 않습니다.

입력 형태(호스트 → 게스트). 다음을 담은 ParseInput 문서입니다.

  • format — 요청된 형식으로, 파서의 parse:<format> 기능 중 하나에서 접두사를 뺀 것입니다.
  • bytes — 소스 바이트입니다.
  • options — 파서별 동작을 위해 소비자가 제공하는 옵션 문서로, 그대로 전달됩니다. 소비자가 제공하지 않으면 없습니다.

출력 형태(게스트 → 호스트). tree(최상위가 객체, 배열 또는 스칼라일 수 있는 JSON 문서로 표현된 파싱된 소스), 공유 Diagnostic 형태의 진단, 원본 바이트에서 트리 노드의 위치를 나타내는 선택적 소스 범위, 그리고 파싱을 완료할 수 없을 때의 실패 error를 담은 ParseOutput 문서입니다. 모든 필드와 그 제약은 생성된 파서 소켓 스키마 레퍼런스에 있습니다.

와이어 인코딩. 입력과 출력 모두 정규 CBOR(RFC 8949 §4.2.1)로 전달되며, 이는 게스트가 같은 ParseInput을 aggrega_parse_source에 넘길 때 쓰이는 인코딩과 같습니다. 게스트는 키트의 ParseInput과 ParseOutput이 이미 갖춘 진입점, 즉 Go의 DecodeCBOR와 EncodeCBOR, Rust의 decode_cbor와 encode_cbor, TypeScript의 decodeCBORParseInput과 encodeCBORParseOutput을 통해 입력을 디코딩하고 출력을 인코딩하며, 바이트를 읽고 씁니다(Rust에서는 Vec<u8>, TypeScript에서는 Host.inputBytes()와 Host.outputBytes(...)). CBOR 라이브러리는 필요 없으며 바이트를 직접 파싱하는 일도 없습니다. 소스 바이트는 원시 바이트열로 전달되고, 생성된 디코더가 이를 키트 고유의 필드 타입에 채웁니다. Go에서는 바이트 슬라이스, Rust와 TypeScript에서는 base64 문자열입니다. options와 tree는 각자의 JSON 문서 바이트로 전달되므로, 파서가 쓴 트리는 소비자에게 그대로 도달합니다. 완료할 수 없는 파서는 출력의 error에 이유를 밝히고, 파싱은 파서와 그 메시지를 지목하며 실패합니다. 이 인코딩의 ParseOutput이 아닌 응답, 즉 JSON으로 작성되었거나 형태가 선언하지 않은 최상위 필드를 담은 응답도 파서와 그 parse export를 지목하며 파싱을 실패시킵니다. 실패한 파싱은 렌더 판정 역할에서 빌드를 중단시키고, 임포터에게는 aggrega_parse_source가 응답하는 실패로 전달됩니다. 파서가 거부하는 소스, 즉 트리와 함께 halt 진단으로 응답하는 소스도 마찬가지입니다. 임포터의 호출은 그러한 각 진단의 메시지와 함께 파서의 순서대로 실패하며, 트리를 전달받지 않습니다. aggrega plugin run-local --export parse로 직접 호출하면, 파서는 작성된 JSON 페이로드를 이 인코딩으로 변환한 것을 전달받고(그 페이로드에서 소스는 JSON이 모든 바이트 필드를 쓰듯 base64로 작성됩니다), 응답은 export의 출력 형태로 읽혀 JSON으로 출력됩니다. 그 형태가 아닌 응답은 빌드가 거부하는 것과 마찬가지로 export를 명시하며 거부됩니다.

타입 정의. 파서 와이어 타입인 ParseInput, ParseOutput, NodeSpan, SourceSpan은 세 ABI 패키지 모두에 게시되고 각 언어의 플러그인 개발 키트가 다시 export하며, 하나의 코덱에서 생성되므로 세 패키지가 항상 일치합니다. 각 키트의 parse 예제는 이 방식으로 입력을 읽고 출력을 쓰며, 바이너리에 포함되어 제공되는 HCL, TOML, YAML, JSON, 주석이 있는 JSON용 파서도 마찬가지입니다.

현재 상태: 사용 가능 — 정책이 기본적으로 읽지 않는 형식의 아티팩트에 대해 렌더 판정 역할에서, 임포터를 위해 aggrega_parse_source를 통해 디스패치되며, 형식을 지정하지 않은 가져오기의 형식을 인식하는 데에도 쓰입니다.

임포터 소켓 — 초안 작성 출력

임포터는 다른 도구용으로 작성된 소스(예: 에이전트 빌더에서 내보낸 플로)를 Aggrega 작성 파일 초안으로 변환합니다. 임포터는 대역 외에서 실행됩니다. aggrega import, 편집기 세션의 aggrega/import 메서드, 어시스턴트용 import 도구는 요청된 형식을 import:<format>으로 알리는 임포터를 확인하고, 가져오기마다 한 번씩 그 임포터의 import 익스포트를 호출합니다. 빌드는 임포터를 디스패치하지 않습니다. 어떤 임포터가 실행되는지, 운영자가 임포터에 무엇을 넘기는지는 소스를 초안으로 변환하는 임포터에서 설명합니다. 컴파일러 자체의 임포터(컴파일러가 읽는 형식마다 하나씩)는 코어 임포터에서 설명합니다. 해당 형식이 무엇인지, 각 임포터가 무엇을 읽고 무엇을 초안으로 만드는지, 받는 설정, 컴파일러 릴리스마다의 배포, 그리고 머신에 아직 없는 임포터를 가져오기가 어떻게 가져와 검증하는지를 다룹니다.

입력 형태(호스트 → 게스트). 다음을 담는 ImportInput 문서입니다.

  • format — 가져오기가 요청한 형식으로, 임포터의 import:<format> 기능 중 하나에서 접두사를 뺀 것입니다.
  • bytes — 소스 바이트입니다. 파일 가져오기에서는 파일 전체이고, 디렉터리 가져오기에서는 비어 있으며 디렉터리의 파일은 sources 아래로 전달됩니다.
  • name — 앞에 디렉터리가 붙지 않은 소스의 이름입니다. 이를 통해 임포터는 보고하는 내용과 초안으로 작성하는 내용에서 소스를 지목할 수 있습니다. 파일을 가져올 때는 bytes를 읽어 온 파일의 기본 이름이고, 디렉터리를 가져올 때는 전체 경로에서 읽은 디렉터리 자체의 기본 이름이므로 aggrega import .는 자신이 실행되는 디렉터리의 이름을 전달하며, 디렉터리의 각 파일은 여전히 각자의 이름으로 전달됩니다. 소스에 줄 이름이 없으면 없습니다.
  • sources — 이름이 붙은 소스로, 각각 이름과 바이트를 담으며 이름순으로 정렬된 하나의 목록입니다. 디렉터리 가져오기에서는 임포터가 선언한 파일 패턴이 선택하는 디렉터리의 모든 파일이 워크스페이스의 빌드 출력 폴더를 제외하고 디렉터리 안의 슬래시로 구분된 경로를 이름으로 하여 들어가고, 이 임포터를 연결하는 plugins.importer 항목이 with.sources 아래에 선언한 파일이 각각 기본 이름으로 들어갑니다. 같은 이름의 디렉터리 파일과 with.sources 파일이 있으면 한쪽이 다른 쪽을 가리는 대신 가져오기가 거부됩니다. 해당하는 것이 없으면 생략됩니다.
  • settings — 해당 항목이 with.settings 아래에 선언한 설정 객체로, 키가 정렬된 JSON 문서로서 그대로 전달됩니다. 임포터를 연결하는 항목이 없거나 항목이 설정을 선언하지 않으면 생략됩니다.
  • catalog — 작업 공간 자체 카탈로그가 보유한 Components의 뷰입니다. 임포터 자신이 선택된 카탈로그, 즉 작업 공간의 카탈로그 폴더 또는 작업 공간이 카탈로그 폴더를 지정하지 않는 경우 기본 레지스트리가 게시하여 이 머신에 보관된 카탈로그 스냅샷을 나타내며, 뷰 자체를 위해서는 아무것도 가져오지 않습니다. components 목록은 Component 이름마다 하나의 항목을 이름순으로 담습니다. 카탈로그가 한 Component의 여러 버전을 보유하면, 항목은 버전 없이 그 Component를 지정하는 참조가 확인되는 버전을 설명합니다. 각 항목은 Component의 name과 version, labels, values와 provides가 선언하는 최상위 키 이름(values와 provides, 각각 정렬됨), 그리고 sockets(각각 소켓의 name과 그 소켓을 통해 연결된 의존성이 충족해야 하는 레이블 selector)를 Component가 선언한 순서대로 담습니다. 다른 Component를 확장하는 Component는 선언한 것과 함께 상속한 것도 담으며, 상속한 소켓이 먼저 옵니다. 뷰는 이름, 버전, 레이블, 셀렉터만 담고 값, 기본값, 시크릿은 결코 담지 않으며, 순서가 고정되어 있으므로 하나의 카탈로그는 하나의 바이트 시퀀스를 만듭니다. 카탈로그가 Component를 보유하지 않으면 생략됩니다.

출력 형태(게스트 → 호스트). 가져오기가 만든 엔티티(각각 기존 카탈로그 엔티티에 대한 참조이거나 초안으로 작성된 본문), 그 배경이 된 매핑 결정, 공유 Diagnostic 형태의 진단, 작성할 스캐폴드 파일, 그리고 가져오기를 완료하지 못했을 때의 실패 error를 담는 ImportOutput 문서입니다. 모든 필드와 그 제약은 생성된 임포터 소켓 스키마 레퍼런스에 있습니다.

와이어 인코딩. 입력과 출력은 모두 정규 CBOR(RFC 8949 §4.2.1)로 전달됩니다. 게스트는 킷의 ImportInput과 ImportOutput이 이미 제공하는 진입점(Go의 DecodeCBOR와 EncodeCBOR, Rust의 decode_cbor와 encode_cbor, TypeScript의 decodeCBORImportInput과 encodeCBORImportOutput)으로 입력을 디코딩하고 출력을 인코딩하며, 바이트를 읽고 씁니다(Rust의 Vec<u8>, TypeScript의 Host.inputBytes()와 Host.outputBytes(...)). CBOR 라이브러리는 필요 없으며 바이트를 직접 파싱하는 곳도 없습니다. settings는 바이너리 문서 안에서 JSON 문서의 바이트로 전달되므로, 게스트는 다른 모든 소켓에서와 마찬가지로 내용을 보려면 이를 JSON으로 파싱합니다. 완료할 수 없는 임포터는 출력의 error에 이유를 적고, 가져오기는 임포터와 그 메시지를 명시하며 중단됩니다. 이 인코딩의 ImportOutput이 아닌 응답(JSON으로 작성되었거나 형태가 선언하지 않은 최상위 필드를 담은 응답)도 임포터와 그 import 익스포트를 명시하며 가져오기를 중단시킵니다. aggrega plugin run-local --export import로 직접 호출하면 임포터는 작성된 JSON 페이로드를 이 인코딩으로 변환한 것을 받고, 그 응답은 익스포트의 출력 형태로 읽혀 JSON으로 출력됩니다. 그 형태가 아닌 응답은 빌드가 거부하는 것과 마찬가지로 익스포트를 명시하며 거부됩니다.

해당 형식의 소스를 인식하는 방법. 가져오기는 형식을 지정하지 않을 수 있으며, 이때 호스트는 자체적으로는 어떤 형식도 알지 못한 채 임포터들이 선언한 내용으로 형식을 인식합니다. 임포터는 describe() 자기 보고의 importer(ImporterContract) 아래에, 자신의 형식인 소스를 인식하는 시그니처의 detect 목록을 선언합니다. 각 DetectSignature는 다음을 지정합니다.

  • syntax — 소스를 파싱할 구문 형식으로, 파서 플러그인이 parse:<syntax>로 알리는 형식입니다(예: json 또는 yaml).
  • files — 소스 이름의 끝부분과 대조하는 선택적 파일 이름 패턴입니다. 세그먼트가 하나이면 파일 자체의 이름과, 슬래시로 구분된 여러 세그먼트이면 경로의 마지막 그만큼의 세그먼트와 대조하며, *, ?, [...]는 한 세그먼트 안에서 일치합니다. 패턴을 선언하지 않은 시그니처는 이름에 관계없이 단일 파일인 소스에 적용되며, 디렉터리의 어떤 파일에도 적용되지 않습니다.
  • match — 파싱된 트리가 모두 충족해야 하는 조건자 목록입니다. 각 조건자는 PathMatch로, 트리의 최상위부터 키를 점으로 연결한 path(정수 세그먼트는 배열 위치를 선택합니다), present, absent, object, array, string, number, boolean 중 하나인 is, 그리고 선택적으로 equals 문자열 또는 prefix 문자열을 가집니다 — 둘 중 최대 하나만 가질 수 있습니다.

가져오기가 형식을 지정하지 않으면, 호스트는 가져오기가 선택 대상으로 삼는 모든 임포터(작업 공간 카탈로그의 임포터와 컴파일러의 코어 임포터)의 시그니처를 식별자와 버전 순으로 대조합니다. 호스트는 구문별로 카탈로그가 제공하는 파서(카탈로그가 파서를 제공하지 않는 구문이면 컴파일러 자체에 포함된 파서)로 구문당 최대 한 번 소스를 파싱하고, 트리에 대해 조건을 평가한 뒤, 시그니처가 일치하는 단 하나의 임포터의 형식으로 소스를 읽습니다. 임포터의 aggrega_parse_source 호출에 응답하는 파서도 바로 이 파서이므로, 임포터는 자신을 인식한 파서를 통해 소스를 읽습니다. 어떤 구문으로 파싱되지 않는 소스는 그 구문을 지정한 시그니처와 일치하지 않습니다. 카탈로그와 컴파일러 모두 파서를 제공하지 않는 구문이 있으면 파서가 없음을 명시하며 인식이 중단됩니다. 어떤 시그니처와도 일치하지 않는 소스는 형식을 요청하며 거부되고, 둘 이상의 형식으로 인식된 소스는 그 형식들을 명시하며 거부됩니다. 시그니처는 소스를 그 임포터가 알리는 모든 형식으로 인식하므로, 소스가 인식되어야 하는 임포터는 하나의 형식을 제공하며, 시그니처를 선언하지 않은 임포터는 형식을 지정해야만 사용됩니다.

importer의 Plugin 엔터티는 같은 목록을 spec.importer.detect로 기록하며, 엔터티가 게스트로부터 생성될 때 describe()에서 도출됩니다. 인식은 이 기록을 읽으므로, 게스트는 형식이 확정될 때까지 로드되지 않습니다. 게스트를 로드하거나 게시할 때 보고가 엔터티의 기록과 다르면 importer.detect를 지목하며 거부하고, 아무것도 기록하지 않은 엔터티는 아무것도 주장하지 않습니다. 디스크립터는 importer가 아닌 plugin에 계약이 선언된 경우, 시그니처가 구문을 지정하지 않거나 잘못된 파일 패턴을 지정한 경우, 그리고 술어가 경로를 지정하지 않거나 일곱 가지 외의 is를 지정하거나 equals와 prefix를 모두 지정한 경우 로드 시 거부됩니다.

컴파일러의 코어 importer와 Go 키트의 import 예제는 이 방식으로 시그니처를 선언합니다. Langflow importer는 소스를 JSON으로 읽고 data.nodes에 배열을 요구합니다. Flowise importer는 nodes와 edges에 배열을, data.nodes에는 아무것도 없을 것을 요구합니다. n8n importer는 nodes에 배열, connections에 객체, edges나 data.nodes에는 아무것도 없을 것을 요구합니다. MCP importer는 클라이언트 구성마다 파일을 지정하는 시그니처를 하나씩 선언합니다. .mcp.json, claude_desktop_config.json, .cursor/mcp.json은 JSON으로 읽고 mcpServers에 객체를 요구하며, .vscode/mcp.json은 Visual Studio Code가 읽는 방식대로 주석 포함 JSON으로 읽고 servers에 객체를 요구합니다. 그리고 파일을 지정하지 않고 https://static.modelcontextprotocol.io/schemas/로 시작하는 $schema 문자열을 요구하는 시그니처 하나를 선언합니다. Compose importer는 소스를 YAML로 읽고, Compose가 기본으로 읽는 파일인 compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml과 그 네 가지 override 파일을 지정하며, services에 객체를 요구합니다. Dify importer는 소스를 YAML로 읽고, 파일을 지정하지 않으며, kind에 문자열 app을, app.mode와 version에 무언가를 요구합니다. CrewAI importer는 트리에 아무것도 요구하지 않고 YAML로 읽는 config/agents.yaml과 config/tasks.yaml, 주석 포함 JSON으로 읽고 agents에 목록을 요구하는 crew.jsonc와 crew.json, 주석 포함 JSON으로 읽고 role에 무언가를 요구하는 agents/*.jsonc와 agents/*.json을 지정하므로, 이 중 어느 둘도 하나의 소스에 함께 일치하지 않으며, 형식을 지정하지 않고 단독으로 가져온 파일은 JSON뿐 아니라 YAML로도 읽힙니다. LangGraph importer는 JSON으로 읽고 graphs에 객체를 요구하는 langgraph.json을 지정하고, 파일을 지정하지 않고 graphs에 객체와 $schema에 문자열 https://langgra.ph/schema.json을 요구하는 시그니처 하나를 선언하며, 환경 파일은 지정하지 않습니다. 인식은 어떤 importer의 패턴이든 선택하는 모든 파일을 읽으므로, 환경 파일을 지정하는 패턴이 있으면 형식을 지정하지 않고 가져오는 모든 디렉터리의 환경 파일이 열리게 되기 때문입니다. Google ADK importer는 YAML로 읽고 name과 instruction에 무언가가 있거나 agent_class에 문자열과 name에 무언가가 있을 것을 요구하는 root_agent.yaml을 지정하며, 다른 파일은 지정하지 않습니다. 하위 에이전트의 구성은 어떤 이름이든 될 수 있고, 모든 YAML 파일을 지정하는 패턴은 형식을 지정하지 않고 가져오는 모든 디렉터리의 YAML 파일을 하나하나 열게 되기 때문입니다. Agent Framework importer는 소스를 YAML로 읽고, 파일을 지정하지 않으며, kind에 문자열 Prompt를, model에 객체를 요구합니다. Go 키트의 import 예제는 소스를 YAML로 읽고 kind에 문자열 DemoSource를 요구합니다. Go에서는 다음과 같습니다.

Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{
Syntax: "json",
Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},
}}},

디렉터리 가져오기가 읽는 것. 소스는 디렉터리일 수 있으며, importer가 선언한 파일 패턴이 무엇을 읽을지 결정합니다. 호스트는 디렉터리의 파일 중 깊이와 관계없이 importer 시그니처의 files 패턴 중 하나가 선택하는 파일만 정확히 읽고(각 패턴은 디렉터리 안에서 파일의 슬래시로 구분된 경로 끝부분과 대조됩니다), 이를 이름 순서대로 sources로 넘기며 bytes는 비워 두고 디렉터리 자체의 이름을 name으로 넘깁니다. 디렉터리의 다른 파일은 열지 않습니다. 워크스페이스 빌드가 렌더링된 파일을 쓰는 폴더(워크스페이스 루트 아래의 dist/)는 그 폴더를 포함하는 디렉터리의 일부로 읽히지 않습니다. 그 폴더의 파일은 하나도 넘겨지거나 인식되지 않으며, 그 폴더로 이어지는 링크는 건너뜁니다. 따라서 빌드된 디렉터리는 그 안에 담긴 프로젝트로 읽히고, 그 폴더 자체이거나 그 안에 있는 디렉터리는 지정한 그대로 읽힙니다. files 패턴을 선언하지 않은 시그니처는 디렉터리의 어떤 파일도 선택하지 않으므로, 패턴을 선언하지 않은 importer는 파일 하나를 읽고 디렉터리는 거부하며, 패턴이 선택하는 파일이 하나도 없는 디렉터리도 거부됩니다. 디렉터리는 그 내부로 한정됩니다. 읽으려는 파일 중 디렉터리 밖으로 이어지는 링크나 디렉터리로 향하는 링크가 디렉터리 밖으로 이어지면 아무것도 읽기 전에 거부되고, 디렉터리로 향하는 링크는 결코 따라 들어가지 않으며, 어떤 패턴도 선택하지 않는 파일로 향하는 링크는 읽지 않고 건너뜁니다. 디렉터리의 형식 인식도 같은 규칙을 따릅니다. 각 시그니처는 그 패턴이 선택하는 파일에 대해 이름 순서로 시도되고, 각 파일은 구문마다 최대 한 번 읽히고 파싱되며, 패턴을 선언하지 않은 시그니처는 그중 어느 파일에도 적용되지 않습니다. 호스트는 아무것도 제한하지 않습니다. importer에게 너무 큰 디렉터리는 importer 자체의 런타임 제한에 의해 거부됩니다. 컴파일러의 Langflow, Flowise, n8n, Dify, Agent Framework importer는 모두 files 패턴을 선언하지 않으므로 각각 파일 하나를 읽습니다. MCP importer는 네 가지 클라이언트 구성의 이름을 선언하므로 디렉터리에 있는 그 파일을 모두 읽고, Compose importer는 여덟 가지 Compose 파일 이름을 선언하므로 디렉터리에 있는 모든 Compose 파일을 넘겨받아 Compose가 읽을 파일들을 병합합니다. CrewAI importer는 CrewAI 프로젝트의 선언이 작성되는 여섯 가지 이름을 선언하므로 프로젝트의 선언을 넘겨받고 프로그램은 전혀 넘겨받지 않습니다. LangGraph importer는 langgraph.json을 선언하므로 애플리케이션의 구성을 넘겨받고 코드나 환경 파일은 전혀 넘겨받지 않으며, 환경 파일은 연결 항목의 with.sources를 통해서만 전달됩니다. Google ADK importer는 root_agent.yaml을 선언하므로 애플리케이션의 루트 에이전트 구성을 넘겨받고 코드나 환경 파일은 전혀 넘겨받지 않으며, 하위 에이전트가 지정하는 구성은 연결 항목의 with.sources를 통해서만 전달됩니다.

타입 정의. importer 와이어 타입인 ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput과 이것이 담는 엔터티, 결정, 스캐폴드 형태는 세 ABI 패키지 모두에 게시되고 각 언어의 플러그인 개발 키트가 다시 내보내며, 하나의 코덱에서 생성되므로 세 패키지가 항상 일치합니다. describe 자체 보고가 담는 인식 타입 ImporterContract, DetectSignature, PathMatch도 마찬가지입니다. Go 키트의 importer 패키지 github.com/aggrega-ai/aggrega-pdk/go/pkg/importer는 형식과 관계없이 importer가 하는 모든 일을 담고 있으며, 모두 이 패키지를 기반으로 만들어진 컴파일러의 코어 importer는 이 방식으로 입력을 읽고 출력을 씁니다.

Go 키트로 만든 importer가 점수를 매기는 대상. 키트의 점수기는 각 소스 노드를 catalog 뷰의 Components와만 비교하여 평가합니다. 후보는 워크스페이스 자체의 카탈로그이며(엔터프라이즈 카탈로그의 Components도 표준 라이브러리의 것과 똑같이 취급됩니다), 키트는 자체 후보를 갖지 않습니다. 각 Component에서는 이름, component.aggrega.ai/category 레이블이 담는 카테고리, 레이블, 그리고 values가 선언하는 키 이름을 읽으며, provides 키와 소켓은 평가하지 않습니다. 카탈로그에 추가된 Component는 importer를 다시 빌드하지 않아도 다음 가져오기에서 후보가 됩니다. 카탈로그에 Component가 없어 뷰가 없는 경우에는 어떤 노드에도 후보가 없습니다. 어떤 노드도 참조되거나 힌트로 제시되지 않으며, 드래프트가 자체 Component를 부여하는 모든 노드는 새로 작성됩니다. 키트를 통해 점수를 매기는 모든 importer는 이 방식으로 점수를 매깁니다. 컴파일러의 Langflow, Flowise, n8n, Compose importer도 여기에 포함되며, MCP importer는 어떤 후보도 평가하지 않습니다. 키트를 사용하지 않는 importer는 원하는 방식대로 뷰를 읽습니다.

Go kit 위에 구축된 importer가 플랫폼의 socket을 읽는 목적. socket은 점수에 아무런 가중치도 주지 않지만, kit는 초안의 배치를 잡기 위해 socket을 읽습니다. 플랫폼이 흐름을 작성된 그대로 실행하는 형식, 즉 Langflow, Flowise, n8n의 형식은 기본적으로 그 흐름을 담은 해당 플랫폼 Component의 인스턴스 하나로 초안이 작성되며, 흐름의 각 부분은 플랫폼의 catalog 항목이 sockets를 나열하는 순서에서, 뷰가 담고 있는 해당 부분 Component의 레이블이 selector를 충족하는 첫 번째 socket에 연결됩니다. selector와 레이블만 읽으며, kit는 자체 selector 문법을 갖고 있지 않으므로 selector는 importer가 제공하는 함수로 매칭됩니다. 뷰에 플랫폼 이름의 Component가 없으면 어떤 부분도 연결되지 않습니다. Core importers에서는 컴파일러의 Langflow, Flowise, n8n importer가 이 방식으로 만드는 초안과, 대신 모든 노드를 각자의 Component로 초안 작성하는 layout 설정을 설명합니다.

현재 상태: 사용 가능 — aggrega import와, 편집기 세션 및 어시스턴트용 도구의 동일한 작업으로 디스패치됩니다.

배치 기준: linter 소켓과 거버넌스 판정 역할

문서화된 소켓 중 두 가지는 비슷한 표면을 공유하지만(둘 다 규칙별 결과를 내보냅니다) 파이프라인 배치와 차단 의미론이 다릅니다. 특정 검사를 어느 소켓이 담당할지 결정하는 기준은 다음과 같습니다.

  • 거버넌스 판정 역할(대역 내, 빌드 중단). 빌드를 중단하는 정책을 위한 것입니다. halt 판정은 컴파일 파이프라인을 멈추며 빌드는 아티팩트를 생성하지 않습니다. 사용 사례는 위반 시 출력을 적용하기에 안전하지 않게 만드는 정책입니다. 컴플라이언스 게이트(PCI / SOC2 경계 배치), 토폴로지 불변 조건(제로 트러스트 인그레스, 경계 간 인증), 자격 증명 흐름의 형태(IR에 평문 시크릿 없음) 등이 있습니다. 정책은 IR 그래프(ir-verdict, 렌더링 전) 또는 렌더링된 아티팩트(render-verdict, 렌더링 후)를 대상으로 추론합니다.
  • 린터 소켓(대역 외, CI / IDE, 권고). 모범 사례 및 발견 가능성 검사를 위한 것입니다. 위반이 의심스럽지만 안전하지 않은 것은 아닌 규칙으로, 고아 시크릿, 사용되지 않는 파라미터, 폐기된 레이블 어휘, 비용 귀속을 위한 태그 완전성, 명명 관례 이탈 등이 있습니다. 실패하면 권고 출력이 생성되며, 빌드는 여전히 아티팩트를 생성합니다.

배치 기준을 하나의 규칙으로 표현하면 다음과 같습니다. 검사가 빌드를 중단해야 한다면 거버넌스 판정 역할에 속하고, 파이프라인을 차단하지 않고 작성자나 검토자에게 경고해야 한다면 린터 소켓에 속합니다.

둘 다 현재 사용할 수 있습니다. 린터 소켓은 aggrega lint를 통해 publishing-linter를 실행하고, 거버넌스 판정 역할은 워크스페이스가 판정 역할 플러그인을 연결하면 aggrega build 중에 대역 내에서 디스패치됩니다. 판정 역할은 자체 심각도를 가진다는 점에 유의하십시오. 정책 자체가 중단 없이 권고하는 warn 및 info 판정을 내보낼 수 있으므로, 위의 중단 대 권고 구분은 검사 전체에 대한 배치 지침이며 정책이 중단만 할 수 있다는 주장이 아닙니다. 심각도 모델은 거버넌스 소켓 페이지를 참조하십시오.

상호 참조

  • policy-socket.md — 거버넌스 소켓에 대한 종합적인 설명: 네 가지 역할, 판정 심각도, 운영자 입력 채널, 컴파일러에 내장된 두 엔진 중 하나를 위한 정책 작성, 외부 정책 엔진 래핑, 그리고 참조 게스트.
  • core-importers.md — 컴파일러 자체 임포터(읽는 형식마다 하나): 각 임포터가 읽는 내용, 설정, 그리고 각 컴파일러 릴리스와 함께 이루어지는 배포.
  • 10-status.md#compilation-pipeline-phases — 상태 페이지의 플러그인 파이프라인 분류(Wasm 플러그인 파이프라인 런타임 준비 상태).
  • architecture/04-entity-taxonomy.md §“Domain 3: Infrastructure Base” — 자격 증명 FeatureRecipes를 위한 Two-Part Plugin Principle(Fetcher + Injector 패턴).
  • architecture/13-catalog-and-registry.md — provider 세그먼트로 시작하는 OCI 분류 체계.
  • entities/featurerecipe.md — FeatureRecipe pipeline: 작성 표면.
  • when-to-use-a-pipeline-step.md — 결정 가이드: 파이프라인 단계와 템플릿 기반 FeatureRecipe 비교.
  • templates/expansion-matrix.md — 플러그인 파이프라인의 pipeline: with: 블록 템플릿 평가 규칙과 .steps 접근 의미론.
  • examples/04-secrets.md — 자격 증명 FeatureRecipe가 취할 수 있는 Fetcher + Injector 파이프라인 형태.
  • errors/error-translation.md — 플러그인 게스트가 참여하는 오류 변환 원칙.