Part.5 · SDK Engine 실습·연동 후보

SDK Engine: 온라인·오프라인 설치와 연동 후보 사용 안내

이 도구의 범위

SDK Engine은 실제 연결이나 Pack 등록 전에 고객이 검토할 연동 후보를 준비합니다. 선언된 읽기 전용 Custom API 작업 또는 MCP 기록과 합성 응답을 검사하고, 값 매핑 소스를 생성하여 로컬 Rust 컴파일러로 빌드합니다. 이 도구는 원천 API·MCP 서버를 호출하거나, 자격 증명을 읽거나, Appliance를 변경하거나, Pack을 등록하거나, Work를 실행하지 않습니다.

패키지에는 합성 예제가 포함됩니다. 선택 세트 경로를 쓰려면 동일 세대의 운영체제별 공용 오프라인 Rust 의존성 패키지를 함께 준비하십시오. 기존 설치 툴체인을 선택한 온라인 경로에서는 이 세트가 필수가 아닙니다. 여기에 네이티브 컴파일러·표준 라이브러리·Cargo와 선언된 정확한 crate 버전이 들어 있으며, 이 범위에서는 Rust나 crate를 따로 다운로드하지 않습니다. 다른 OS·새 crate·다른 타깃은 별도 검증 대상입니다. macOS arm64와 Debian 13 amd64 패키지는 Rust 1.96.0, Windows amd64 패키지는 Rust 1.97.1을 사용합니다.

네이티브 전제 조건은 별도입니다. Debian은 기존 시스템 C 링커·libc 개발 파일, macOS는 신뢰 검증을 통과하는 Apple 개발 도구·SDK, Windows는 Visual Studio 2022 BuildTools의 MSVC 14.44.35207 및 Windows SDK 10.0.26100.0이 필요합니다. 이 자산은 Rust 의존성 패키지에 재배포하지 않습니다. 새 OS에 이 전제 조건까지 설치한다는 범위는 검증하지 않았습니다.

macOS의 run-offline은 기본적으로 현재 Apple 개발 도구 선택(SYSTEM_ACTIVE)을 사용합니다. 이미 설치된 Command Line Tools를 실행 한 번에 명시적으로 선택하려면 의존성 경로 뒤에 --macos-developer-selection COMMAND_LINE_TOOLS를 붙이십시오. 등록된 /Library/Developer/CommandLineTools 설치를 선택하며 기존 신뢰 검사를 모두 적용합니다. 시스템 개발 도구 설정을 바꾸거나 다른 설치로 자동 전환하지 않습니다. 다른 운영체제에서는 이 옵션을 거부합니다.

./bin/packr-sdk-engine run-offline examples/read-only-custom-api.json ./quality-candidate /absolute/path/dependencies --macos-developer-selection COMMAND_LINE_TOOLS

공식 서명·공증, 고객 활성화·전달의 상태는 해당 패키지와 별도로 신뢰하는 릴리스 목록에서 확인하십시오. 로컬 예제 성공만으로 그 상태를 승인하지 않습니다.

먼저 운영 환경을 선택하십시오: 온라인과 오프라인

SDK Engine은 온라인 개발 환경과 오프라인 환경 모두에서 사용할 수 있습니다. 오프라인 의존성 세트는 인터넷이 차단된 온프렘에서 SDK가 어댑터를 컴파일할 때 필요한 Rust 자산을 미리 준비하기 위한 선택 구성입니다. 제품의 기본 운영 모드를 오프라인으로 고정하는 설정이 아닙니다. SDK에서 새 연동 후보를 빌드할 때 생길 수 있는 의존성 문제를 해결하는 데 목적이 있습니다.

온라인 환경에서 기존 설치 툴체인을 사용하는 호환 경로는 다음과 같습니다. 압축을 푼 SDK 디렉터리에서 rustc --version으로 실제 선택되는 컴파일러를 확인하고, 지원 버전·타깃·OS 도구를 준비한 다음 새 출력 폴더를 지정하십시오. 이 경로는 PATH의 컴파일러를 사용하며 별도 의존성 세트의 전체 파일·네이티브 신뢰 영수증을 제공하지 않습니다. 해당 환경에서 별도로 검증해야 합니다.

rustc --version
./bin/packr-sdk-engine analyze examples/read-only-custom-api.json unused
./bin/packr-sdk-engine run examples/read-only-custom-api.json ./online-custom-candidate-01
./bin/packr-sdk-engine run examples/read-only-mcp-transcript.json ./online-mcp-candidate-01

rustc --version
if ($LASTEXITCODE -ne 0) { throw 'Rust compiler unavailable' }
.\bin\packr-sdk-engine.exe analyze .\examples\read-only-custom-api.json unused
if ($LASTEXITCODE -ne 0) { throw 'Analyze failed' }
.\bin\packr-sdk-engine.exe run .\examples\read-only-custom-api.json .\online-custom-candidate-01
if ($LASTEXITCODE -ne 0) { throw 'Custom candidate failed' }
.\bin\packr-sdk-engine.exe run .\examples\read-only-mcp-transcript.json .\online-mcp-candidate-01
if ($LASTEXITCODE -ne 0) { throw 'MCP candidate failed' }

run은 설치된 컴파일러를 쓰는 호환 명령으로 유지되어 있습니다. 현재 패키지의 별도 의존성 검증 경로와 같다고 해석하지 마십시오. run-offline의 신뢰·권한 검사에 실패한 뒤 그 검사를 피하기 위한 대체 실행으로 사용하지 않습니다. 아래의 검증된 의존성 세트 절차는 온라인 환경에서도 선택할 수 있습니다. 어느 경로의 합성 예제도 실제 API나 MCP 서버에 접속하지 않습니다.

두 압축 파일을 구분하고 새 위치에 준비하기

SDK 본체에는 bin, docs, examples, 라이선스·고지가 있습니다. Rust 의존성 세트에는 DEPENDENCIES.json, FILES.json, toolchain, cargo-home과 고지가 있습니다. 본체만 해제했다고 선택 구성인 의존성 세트까지 설치된 것은 아닙니다. 기존 설치와 결과를 보존하려면 세대별 새 위치를 선택하십시오.

macOS에서는 shasum -a 256, Debian에서는 sha256sum, Windows에서는 Get-FileHash -Algorithm SHA256으로 두 압축 파일을 각각 확인합니다. 동일 위치에서 받은 해시만으로 공급자 신원이 증명되지는 않습니다. 별도로 신뢰하는 구성요소 목록과 비교하십시오. 파일 이름이 같아도 해시가 다르면 진행하지 않습니다.

Linux·macOS에서 아래 경로를 실제 파일로 바꾸고 실행합니다. 예제의 루트는 기존에 존재하면 중단합니다. 개인 홈의 비공유 경로를 사용하고, 상위 경로도 다른 사용자가 수정할 수 없어야 합니다.

sdk_archive="/absolute/path/sdk-package.tar.gz"
deps_archive="/absolute/path/RUST_DEPENDENCIES_OS.tar.gz"
install_root="$HOME/VibePackr-SDK-install-01"
test ! -e "$install_root" || exit 1
umask 077
mkdir -m 700 "$install_root" || exit 1
mkdir "$install_root/sdk" "$install_root/dependencies" "$install_root/runs" || exit 1
tar -xzf "$sdk_archive" -C "$install_root/sdk" || exit 1
tar -xzf "$deps_archive" -C "$install_root/dependencies" || exit 1
cd "$install_root/sdk" || exit 1

Windows PowerShell 5.1에서는 접근이 제한된 사용자 홈 아래의 새 디렉터리를 준비합니다. 공유·동기화·네트워크 경로를 사용하지 말고 조직이 승인한 현재 사용자 전용 경로와 ACL을 확인하십시오. 아래는 이미 해당 권한이 확인된 부모 경로를 가정합니다. 기존 디렉터리를 덮어쓰거나 시스템 전체 ACL을 바꾸지 않습니다.

$sdkArchive = 'C:\absolute\path\sdk-package.zip'
$depsArchive = 'C:\absolute\path\RUST_DEPENDENCIES_WINDOWS_AMD64.zip'
$installRoot = Join-Path $env:USERPROFILE 'VibePackr-SDK-install-01'
if (Test-Path -LiteralPath $installRoot) { throw 'Choose a fresh install root' }
New-Item -ItemType Directory -Path $installRoot -ErrorAction Stop | Out-Null
$sdkRoot = Join-Path $installRoot 'sdk'
$depsRoot = Join-Path $installRoot 'dependencies'
$runsRoot = Join-Path $installRoot 'runs'
New-Item -ItemType Directory -Path $sdkRoot,$depsRoot,$runsRoot -ErrorAction Stop | Out-Null
Expand-Archive -LiteralPath $sdkArchive -DestinationPath $sdkRoot -ErrorAction Stop
Expand-Archive -LiteralPath $depsArchive -DestinationPath $depsRoot -ErrorAction Stop
Set-Location -LiteralPath $sdkRoot

다음 단계에서 전체 의존성 검증이 권한 문제로 거부되면 해당 설치를 사용하지 말고 승인된 설치 절차로 해결하십시오. 검사 완화, 관리자 권한 실행, 실행 정책 우회, 시스템 신뢰 저장소 변경을 해결 방법으로 사용하지 않습니다. 온라인에서 기존 툴체인만 쓰는 경우 의존성 압축 해제 단계는 선택 사항입니다.

제공 파일 확인과 설치

1. 받은 릴리스 목록에 현재 운영체제용 SDK Engine이 있는지 확인하십시오. SDK와 의존성 압축 파일의 SHA-256을 별도로 신뢰하는 릴리스 목록과 대조하십시오. 서명이 있는 릴리스만 해당 서명을 검증하십시오. 공식 배포 서명이 없는 후보는 그 사실을 기록하고 서명된 릴리스와 구분하십시오. 다른 운영체제용 파일을 대신 사용하지 마십시오.
2. 접근이 제한된 새 디렉터리에 압축을 풀고 bin, docs, examples를 함께 보관하십시오. 시스템 전체에 설치할 때는 해당 릴리스의 운영체제별 안내를 따르십시오.
3. 의존성 패키지도 신뢰하는 현재 사용자만 쓸 수 있는 별도의 새 디렉터리에 해제하십시오. 모든 중간 디렉터리에 다른 사용자의 쓰기 권한이 없어야 합니다. 포함된 cargo-home은 검증 입력으로 보존하며 작업 캐시로 직접 쓰거나 전역 캐시에 병합하지 마십시오. 활성화 스크립트나 셸 세션 변경은 필요하지 않습니다. 아래 의존성 절대 경로를 실제 경로로 바꾼 뒤 전체 파일 검증과 예제 확인을 수행하십시오.

Linux 또는 macOS 터미널:

./bin/packr-sdk-engine verify-offline-dependencies DEBIAN_13_AMD64 /absolute/path/dependencies
# macOS arm64: DEBIAN_13_AMD64 대신 MACOS_ARM64
test -f examples/read-only-custom-api.json
test -f examples/read-only-mcp-transcript.json
./bin/packr-sdk-engine analyze examples/read-only-custom-api.json unused

Windows PowerShell:

.\bin\packr-sdk-engine.exe verify-offline-dependencies WINDOWS_AMD64 C:\absolute\path\dependencies
Test-Path .\examples\read-only-custom-api.json
Test-Path .\examples\read-only-mcp-transcript.json
.\bin\packr-sdk-engine.exe analyze .\examples\read-only-custom-api.json unused

analyze는 입력만 읽고 출력 디렉터리를 만들지 않습니다. 성공 결과에도 authority_granted: false가 표시됩니다. 릴리스 목록에 SDK Engine이 없으면 진행을 멈추고 해당 릴리스의 지원 경로에서 올바른 패키지를 받으십시오.

선택한 의존성 세트로 OS별 예제 실행

아래는 앞 단계의 경로 변수가 같은 셸에 남아 있다는 가정입니다. 새 셸에서는 실제 절대 경로를 다시 지정하십시오. analyze의 마지막 unused는 CLI 형식에 필요한 자리이며 결과 폴더가 아닙니다.

macOS ARM64에서 이미 설치된 Command Line Tools를 명시적으로 선택하는 예입니다. 기본 선택은 SYSTEM_ACTIVE이며 아래 옵션은 이 한 실행에만 적용됩니다.

./bin/packr-sdk-engine verify-offline-dependencies MACOS_ARM64 "$install_root/dependencies" || exit 1
./bin/packr-sdk-engine analyze examples/read-only-custom-api.json unused || exit 1
./bin/packr-sdk-engine run-offline examples/read-only-custom-api.json "$install_root/runs/custom-01" "$install_root/dependencies" --macos-developer-selection COMMAND_LINE_TOOLS || exit 1
./bin/packr-sdk-engine run-offline examples/read-only-mcp-transcript.json "$install_root/runs/mcp-01" "$install_root/dependencies" --macos-developer-selection COMMAND_LINE_TOOLS || exit 1

Debian 13 AMD64:

./bin/packr-sdk-engine verify-offline-dependencies DEBIAN_13_AMD64 "$install_root/dependencies" || exit 1
./bin/packr-sdk-engine analyze examples/read-only-custom-api.json unused || exit 1
./bin/packr-sdk-engine run-offline examples/read-only-custom-api.json "$install_root/runs/custom-01" "$install_root/dependencies" || exit 1
./bin/packr-sdk-engine run-offline examples/read-only-mcp-transcript.json "$install_root/runs/mcp-01" "$install_root/dependencies" || exit 1

Windows AMD64:

.\bin\packr-sdk-engine.exe verify-offline-dependencies WINDOWS_AMD64 $depsRoot
if ($LASTEXITCODE -ne 0) { throw 'Dependency verification failed' }
.\bin\packr-sdk-engine.exe analyze .\examples\read-only-custom-api.json unused
if ($LASTEXITCODE -ne 0) { throw 'Analyze failed' }
.\bin\packr-sdk-engine.exe run-offline .\examples\read-only-custom-api.json (Join-Path $runsRoot 'custom-01') $depsRoot
if ($LASTEXITCODE -ne 0) { throw 'Custom candidate failed' }
.\bin\packr-sdk-engine.exe run-offline .\examples\read-only-mcp-transcript.json (Join-Path $runsRoot 'mcp-01') $depsRoot
if ($LASTEXITCODE -ne 0) { throw 'MCP candidate failed' }

첫 예제의 결과 확인과 새 터미널에서 재개

앞의 OS별 설치·실행 블록으로 Custom과 MCP를 각각 새 폴더에 실행한 뒤 아래를 확인합니다. SDK는 바탕화면 앱 아이콘을 만드는 설치 프로그램이 아니므로 앱 목록 대신 해제한 bin의 실행 파일과 결과 경로를 찾습니다. 명령은 그 SDK 디렉터리에서 실행합니다. 본체만 쓰는 온라인 경로에서는 선택 의존성 변수를 만들 필요가 없습니다.

기존 툴체인의 온라인 run 예제를 그대로 사용했다면 결과는 SDK 폴더 아래 online-custom-candidate-01과 online-mcp-candidate-01입니다. 아래 조회 명령의 경로를 그 실제 결과로 바꾸십시오. runs/custom-01과 runs/mcp-01은 앞의 선택 세트 실행 블록이 만든 경로입니다.

Custom 결과를 실제로 열어 보기

ls -la "$install_root/runs/custom-01"
cat "$install_root/runs/custom-01/README.md"
cat "$install_root/runs/custom-01/adapter.rs"
cat "$install_root/runs/custom-01/manifest.json"

$candidate01 = Join-Path $runsRoot 'custom-01'
Get-ChildItem -LiteralPath $candidate01
Get-Content -LiteralPath (Join-Path $candidate01 'README.md') -Raw -Encoding UTF8
Get-Content -LiteralPath (Join-Path $candidate01 'adapter.rs') -Raw -Encoding UTF8
Get-Content -LiteralPath (Join-Path $candidate01 'manifest.json') -Raw -Encoding UTF8

libadapter.rlib는 Rust 라이브러리이며 더블클릭하거나 운영체제 실행 파일처럼 실행하지 않습니다. 결과에서 97이 quality_score 정수로 매핑되는 것은 합성 검증의 내용입니다. 실제 서버의 응답을 받았다는 뜻이 아닙니다. 원본 입력 값을 읽고 매핑·단계 기록과 대조하십시오.

input.json 사본을 만드는 빠진 준비 단계

아래 명령은 새 inputs-02 폴더에 전체 예제를 복사합니다. 이 절에서는 편집·분석까지 진행하고, 뒤의 input.json을 바꾸고 두 번째 후보 만들기에서 재실행합니다. 같은 이름이 있으면 새 번호를 고르십시오.

test ! -e "$install_root/inputs-02" || exit 1
mkdir "$install_root/inputs-02" || exit 1
cp ./examples/read-only-custom-api.json "$install_root/inputs-02/input.json" || exit 1

$inputs02 = Join-Path $installRoot 'inputs-02'
if (Test-Path -LiteralPath $inputs02) { throw 'Choose a fresh input folder' }
New-Item -ItemType Directory -Path $inputs02 -ErrorAction Stop | Out-Null
Copy-Item -LiteralPath .\examples\read-only-custom-api.json -Destination (Join-Path $inputs02 'input.json') -ErrorAction Stop

편집기에서 이 사본을 열어 score는 문자열 "88", component는 "my-test-component"로 바꿉니다. 매핑을 유지한 값 변경은 adapter.rs를 바꾸지 않을 수 있습니다. 첫 결과와 수정 결과를 모두 보존합니다.

새 터미널을 열었을 때

아래는 기존 설치 경로를 다시 지정하는 명령입니다. 압축을 다시 풀거나 기존 결과를 지우지 않습니다. 앞서 다른 루트명을 사용했다면 그 경로로 바꾸십시오. 다음 실행의 결과 폴더는 다시 새 이름을 선택합니다.

install_root="$HOME/VibePackr-SDK-install-01"
test -f "$install_root/sdk/bin/packr-sdk-engine" || exit 1
cd "$install_root/sdk" || exit 1

$installRoot = Join-Path $env:USERPROFILE 'VibePackr-SDK-install-01'
$sdkRoot = Join-Path $installRoot 'sdk'
$depsRoot = Join-Path $installRoot 'dependencies'
$runsRoot = Join-Path $installRoot 'runs'
Set-Location -LiteralPath $sdkRoot -ErrorAction Stop
if (!(Test-Path -LiteralPath '.\bin\packr-sdk-engine.exe' -PathType Leaf)) { throw 'SDK path does not match the prior installation' }

복귀 경로: 프로그램 경로를 찾지 못함 → 설치 루트·중첩 해제 폴더 확인, analyze 거부 → 전체 입력/인코딩 확인, build 거부 → 선택 의존성·네이티브 전제 조건 확인, 출력 경로 거부 → 새 이름 선택. 실패한 임시 stage를 성공 결과로 열지 않습니다.

포함된 실제 예제

예제의 read_quality 작업은 합성 응답의 component와 문자열 score를 읽습니다. 목표 Contract는 component와 정수 quality_score를 요구합니다. 아래 매핑은 로컬 준비용입니다.

{
  "definition": {
    "integration_id": "acme-quality-hub",
    "operation_id": "read_quality",
    "credential_requirements": [],
    "execution_boundary": "READ_ONLY_SYNTHETIC_SANDBOX"
  },
  "mapping": {
    "field_mappings": [
      {"source": "component", "target": "component", "transform": "IDENTITY"},
      {"source": "score", "target": "quality_score", "transform": "STRING_TO_INTEGER"}
    ]
  },
  "fixture": {
    "scope": "LOCAL_SYNTHETIC_SANDBOX",
    "response": {"component": "fixture-component", "score": "97"}
  }
}

이 발췌는 필드를 설명하기 위한 것입니다. 실행에는 정확한 Contract·어댑터·스키마 지문·권한·증거 범위를 포함한 패키지의 전체 JSON 파일을 사용하십시오. 예제에 암호, 토큰, 개인키 또는 실제 고객 응답을 넣지 마십시오.

예제: MCP로 제공되는 레거시 저장소

조직의 레거시 저장소가 지원되는 MCP 인터페이스를 제공한다면 examples/read-only-mcp-transcript.json부터 확인하십시오. 합성 기록에는 tools/list와 읽기 전용 read_repository 도구가 선언되어 있습니다. 매핑은 name을 repository_id로, sha를 revision으로 복사합니다. Engine은 제공된 기록을 분석하며 MCP 서버에 접속하지 않습니다.

./bin/packr-sdk-engine analyze examples/read-only-mcp-transcript.json unused
./bin/packr-sdk-engine run-offline examples/read-only-mcp-transcript.json ./repository-candidate /absolute/path/dependencies

Windows PowerShell:

.\bin\packr-sdk-engine.exe analyze .\examples\read-only-mcp-transcript.json unused
.\bin\packr-sdk-engine.exe run-offline .\examples\read-only-mcp-transcript.json .\repository-candidate C:\absolute\path\dependencies

고객 선언으로 바꾸기 전에 연동 담당자와 작업 ID, 필드 형식, 읽기 전용 권한, Contract 버전, 합성 응답을 정확히 대조하십시오. 실제 MCP 호출과 자격 증명 사용에는 별도의 승인된 연결 절차가 필요합니다.

다섯 단계 실행

압축을 푼 디렉터리에서 아직 존재하지 않는 출력 경로를 지정하십시오.

./bin/packr-sdk-engine run-offline examples/read-only-custom-api.json ./quality-candidate /absolute/path/dependencies

Windows:

.\bin\packr-sdk-engine.exe run-offline .\examples\read-only-custom-api.json .\quality-candidate C:\absolute\path\dependencies

한 명령이 다음 단계를 순서대로 수행합니다.

1. ANALYZE_GAP: 등록된 Contract·어댑터·프로토콜 버전, 읽기 전용 작업, 입력 크기와 합성 응답을 검사합니다.
2. GENERATE: 로컬 값 매핑 함수인 adapter.rs를 만듭니다. API 전송·자격 증명·Work 실행 코드는 없습니다.
3. BUILD: 전체 파일 검증을 통과한 패키지 내 rustc 절대 경로로 생성 소스를 libadapter.rlib로 컴파일합니다.
4. VALIDATE: 임시 합성 응답 검사를 컴파일·실행하여 예상 매핑과 미선언 필드 거부를 확인합니다. 성공 후 임시 검사 소스와 실행 파일을 제거합니다.
5. PACKAGE: README.md와 manifest.json을 씁니다. 매니페스트에는 입력 지문, 컴파일러 버전, 후보 파일 세 개의 SHA-256과 단계별 입력·출력 지문이 기록됩니다.

성공한 출력 디렉터리에는 adapter.rs, libadapter.rlib, README.md, manifest.json만 있어야 합니다. v2 매니페스트의 offline_execution에는 전체 트리의 전후 지문, 컴파일러·네이티브 도구·환경·명령 인자의 최소 공개 지문이 포함됩니다. 이는 미서명 관측 기록이며 독립적인 실행 증명이나 릴리스 서명이 아닙니다. 매니페스트를 확인하십시오. 결과 CUSTOMER_REVIEW_CANDIDATE는 실제 연결이나 실행 승인을 뜻하지 않습니다.

input.json을 바꾸고 두 번째 후보 만들기

먼저 패키지의 전체 examples/read-only-custom-api.json을 새 입력 작업 폴더의 input.json으로 복사합니다. 제공 예제와 첫 결과는 보존합니다. 편집기에서 다음 두 값만 수정해 UTF-8로 저장하십시오. 파일 전체를 아래 발췌로 교체하지 마십시오.

draft.fixture.response.component = "my-test-component"
draft.fixture.response.score = "88"

score는 문자열이므로 따옴표를 유지합니다. 이 예제의 STRING_TO_INTEGER가 결과의 정수 quality_score로 변환합니다. Contract ID, 어댑터 리비전, 스키마 지문, 권한, 증거 항목은 다른 값을 추측해 바꾸지 않습니다. Windows PowerShell 5.1의 기본 Out-File은 UTF-16을 쓸 수 있으므로 JSON 편집기는 UTF-8을 선택하십시오.

예를 들어 앞서 준비한 설치 루트에 inputs-02를 새로 만들고 그 안에 input.json을 저장한 뒤 실행합니다. macOS는 앞서 선택한 Apple 도구 옵션을 그대로 적용하십시오. 첫 결과와 두 번째 결과를 합치지 않습니다.

./bin/packr-sdk-engine analyze "$install_root/inputs-02/input.json" unused
./bin/packr-sdk-engine run-offline "$install_root/inputs-02/input.json" "$install_root/runs/custom-api-candidate-02" "$install_root/dependencies"
# macOS CLT 선택 시 마지막에 다음 인자를 추가: --macos-developer-selection COMMAND_LINE_TOOLS

$input02 = Join-Path $installRoot 'inputs-02\input.json'
.\bin\packr-sdk-engine.exe analyze $input02 unused
if ($LASTEXITCODE -ne 0) { throw 'Analyze failed' }
.\bin\packr-sdk-engine.exe run-offline $input02 (Join-Path $runsRoot 'custom-api-candidate-02') $depsRoot
if ($LASTEXITCODE -ne 0) { throw 'Candidate failed' }

온라인의 기존 툴체인 경로를 선택했다면 같은 입력과 새 결과 경로로 run을 사용하며 의존성 경로와 macOS 선택 옵션은 넣지 않습니다. 한 후보의 기록에 두 실행 경로의 결과를 섞지 않습니다.

adapter.rs·manifest.json을 읽고 결과 비교하기

adapter.rs는 필드 매핑 코드입니다. 합성 응답의 값만 바꾸고 매핑 규칙을 유지하면 코드가 같을 수 있습니다. manifest.json은 해당 실행의 입력·산출물·단계 기록이므로 입력 지문, 경로, 관측값 등은 달라질 수 있습니다. 다른 OS·컴파일러 버전의 .rlib 해시를 같아야 한다고 가정하지 않습니다.

cat "$install_root/runs/custom-api-candidate-02/adapter.rs"
cat "$install_root/runs/custom-api-candidate-02/manifest.json"

Get-Content -LiteralPath (Join-Path $runsRoot 'custom-api-candidate-02\adapter.rs')
Get-Content -LiteralPath (Join-Path $runsRoot 'custom-api-candidate-02\manifest.json') -Raw
Get-FileHash -LiteralPath (Join-Path $runsRoot 'custom-api-candidate-02\libadapter.rlib') -Algorithm SHA256

생성 코드를 직접 편집하면 기존 매니페스트의 지문과 맞지 않습니다. Engine의 재현 가능한 후보를 만들려면 입력 JSON의 지원되는 선언·매핑을 수정하고 새 결과 경로에서 다시 실행합니다. 매니페스트를 고쳐 기존 실행이 검증된 것처럼 만들지 않습니다. 임의 Rust 코드·추가 crate·실제 네트워크 연동은 이 합성 예제의 검증 범위에 포함되지 않습니다.

재현성은 같은 OS·동일 SDK·컴파일러·의존성·전체 입력으로 새 폴더에 실행한 뒤 adapter.rs와 libadapter.rlib의 SHA-256을 비교합니다. 입력을 바꾼 두 실행 비교와 같은 입력의 재현성 비교는 구분하십시오. 매니페스트 전체 해시까지 같아야 하는 것은 아닙니다. 두 출력의 다섯 단계, 파일 지문, 입력 지문과 의존성 전후 지문도 함께 확인합니다.

문제 상황과 조치

run-offline은 비공개 sibling stage에서 생성·검사하고, 후검사가 끝나면 기존 경로를 덮어쓰지 않는 원자적 이동으로 새 결과를 게시합니다. 실패하면 최종 결과 경로는 없고 비공개 stage·실패 기록이 남을 수 있습니다. 이 stage를 후보 패키지로 사용하지 마십시오. 이전 실패 stage나 결과는 자동으로 재사용하지 않습니다. 지원에 오류 출력을 전달할 때 고객 데이터나 비밀값을 먼저 제거하십시오.

업데이트·보관·제거와 보안 검토 자료

새 SDK는 별도 세대 디렉터리에 해제하고 그 세대의 의존성·지문 목록과 대조합니다. 이전 결과·입력·패키지를 보존한 채 새 위치에서 검증한 다음 작업 경로를 바꿉니다. 되돌릴 때는 기록된 이전 SDK와 그에 맞는 의존성·입력 조합을 선택합니다. 자동 덮어쓰기나 기존 후보의 재사용은 하지 않습니다.

제거 전에 입력 JSON, 수정 내역, 후보 파일·매니페스트와 지원 기록을 보관합니다. 휴대형 설치 디렉터리와 작업 결과 디렉터리를 구분해 관리하십시오. 이 절차는 시스템 서비스나 전역 Rustup·Cargo 설정을 설치하지 않으므로 이를 삭제하거나 시스템 설정을 되돌리는 명령도 필요하지 않습니다. 기존 조직 툴체인을 별도로 제거하지 않습니다.

보안 검토에는 패키지·의존성 지문, 정확한 버전·OS, 파일 목록, LICENSE·NOTICE, 제공된 SBOM·취약점 조회 시점, 실제 검사 결과와 범위를 함께 전달합니다. 서명·공증이 없는 후보와 서명된 릴리스는 구분합니다. 지문 일치는 파일 동일성에 대한 확인이며, 매니페스트는 독립적인 실행 증명이 아닙니다. 알려진 마커 검사는 모든 비밀정보 부재를 보장하지 않으며 공급망·권한·네트워크 격리·최신 취약점 전부를 인증하지 않습니다.

Appliance 등록, 실제 연결, 고객 활성화·전달, Work 실행은 각 릴리스가 별도로 제공한 절차와 승인 범위를 따릅니다. 설치 후 도구 목록으로 돌아가거나, 소스 Document 안내에서 다음 연동 선언을 준비하십시오.

지원 기록

SDK·의존성 패키지 지문과 제공된 서명 유무, 컴퓨터 운영체제, 검증된 컴파일러 버전, 입력 JSON 지문, 대상 Contract·어댑터 버전, 단계 결과, 후보 매니페스트, 연동 담당자를 기록하십시오. 이후 실제 Work가 실행되면 별도의 Appliance 등록 결정과 Work 영수증을 보관하십시오. 지원 기록에는 비밀값과 실제 고객 응답을 넣지 마십시오.

도구별 문제 해결 사례 읽기

다음은 지원되는 입력·명령·권한 경계를 바탕으로 구성한 교육용 사례입니다. 제품의 실제 상태·사유와 함께 읽고, 자신의 실행 기록 없이 예시의 결과를 성공 이력으로 사용하지 않습니다. 온라인과 오프라인 환경 모두에 적용되는 확인 항목과 선택 의존성 경로에만 해당하는 항목을 구별합니다.

상세 예시 SDK-1: SDK 본체만 해제한 뒤 의존성·네이티브 전제 조건 구별

상황: SDK 실행 파일은 열리지만 선택 의존성 경로의 예제 빌드가 시작되지 않습니다. 본체 설치, Rust 세트 검증, OS 네이티브 도구 준비를 한 단계로 합치지 않고 각각 확인합니다.

관찰을 이렇게 나눠 읽습니다.

• 본체: bin·docs·examples 존재는 SDK 파일 준비만 확인합니다.
• 의존성: 같은 OS용 DEPENDENCIES.json·FILES.json·toolchain이 별도 경로에 있어야 합니다.
• 네이티브 도구: Rust 세트와 별도로 릴리스 전제 조건이 충족돼야 합니다.

확인·조치 순서:

1. 온라인 기존 툴체인 경로인지 선택 세트 경로인지 먼저 기록합니다. 이 예시는 후자입니다.
2. SDK·세트의 압축 파일 지문과 플랫폼을 대조하고 정확한 절대 경로로 verify-offline-dependencies를 수행합니다.
3. 트리 검증 뒤에도 거부되면 네이티브 전제 조건·경로 권한·제품 사유를 확인합니다. 실패를 피하려고 다른 실행 경로로 바꾸지 않습니다.

다음 단계로 돌아갈 조건: 선택한 경로의 전제 조건이 충족되고 새 출력에서 다섯 단계가 검증돼야 후보 준비 완료로 기록합니다.

해결되지 않았을 때: 필요 자산 또는 지원 조합이 없으면 정확한 누락 항목을 인계합니다. 임의 다운로드·전역 캐시 혼합으로 빈칸을 메우지 않습니다.

상세 예시 SDK-2: macOS에서 설치된 CLT를 한 실행에 선택

상황: macOS에 Apple 개발 도구가 둘 이상 있습니다. 현재 시스템 선택을 사용하는 실행이 거부됐고, 등록된 Command Line Tools 설치가 별도로 준비돼 있습니다. 설치돼 있다는 사실만으로 신뢰 검증 성공을 가정하지 않습니다.

관찰을 이렇게 나눠 읽습니다.

• 기본 선택: SYSTEM_ACTIVE입니다. 전체 제품의 온라인·오프라인 기본값과 다른 설정입니다.
• 선택 옵션: COMMAND_LINE_TOOLS는 이미 설치된 등록 경로를 지정합니다.
• 신뢰 검사: 선택 후에도 그대로 적용됩니다.

확인·조치 순서:

1. 현재 SDK·의존성 세대와 Apple 도구·SDK 전제 조건을 확인합니다.
2. run-offline의 의존성 경로 뒤에 문서화된 --macos-developer-selection COMMAND_LINE_TOOLS를 명시하고 새 결과 폴더를 지정합니다.
3. 거부가 계속되면 정확한 사유를 보존합니다. 시스템 개발 도구 선택·신뢰 저장소·공식 서명 상태를 바꿔 해결하지 않습니다.

다음 단계로 돌아갈 조건: 해당 실행의 선택된 도구와 후보 검증 결과가 확인돼야 이 경로의 성공으로 기록합니다.

해결되지 않았을 때: CLT가 없거나 신뢰 검증이 거부되면 그 전제 조건을 인계합니다. 이 옵션을 다른 OS에 사용하지 않습니다.

상세 예시 SDK-3: score를 숫자로 바꾸거나 전체 JSON을 발췌로 교체함

상황: 사용자가 예제의 점수를 88로 바꾸면서 문자열 따옴표를 지웠거나 설명용 JSON 발췌만 input.json에 저장했습니다. JSON 문법이 맞아도 선언된 입력 형식과 전체 요청 구조는 별도로 검사됩니다.

관찰을 이렇게 나눠 읽습니다.

• 원본 예제: 전체 request_id·correlation_id·draft를 포함합니다.
• score: 원본 선언은 문자열을 요구합니다. 변환 대상은 정수 quality_score입니다.
• 저장 인코딩: Windows PowerShell 5.1의 기본 파일 출력은 UTF-8과 다를 수 있습니다.

확인·조치 순서:

1. 원본 전체 예제를 새 입력 경로에 복사하고 draft.fixture.response.score를 "88", component를 "my-test-component"로 바꿉니다.
2. UTF-8 저장과 전체 선언을 확인한 뒤 analyze 결과를 읽습니다. 목표 ID·스키마 지문을 추측해 고치지 않습니다.
3. 선택한 실행 경로로 새 결과를 만들고 매니페스트·생성 소스·라이브러리를 함께 확인합니다.

다음 단계로 돌아갈 조건: 수정 입력이 지원 형식으로 받아들여지고 같은 실행의 다섯 단계·산출물 지문이 확인되면 해당 후보만 완료로 기록합니다.

해결되지 않았을 때: 대상·권한·데이터 경계 거부가 남으면 예제 값을 바꾸는 것으로 해결됐다고 표시하지 않습니다.

상세 예시 SDK-4: adapter.rs는 같은데 라이브러리 지문이 다름

상황: 두 출력의 adapter.rs는 같지만 libadapter.rlib의 지문이 다릅니다. 출력 경로만 비교하기 전에 실제 입력·OS·컴파일러·SDK·의존성과 선택한 명령이 같은지 확인해야 합니다.

관찰을 이렇게 나눠 읽습니다.

• 소스 지문 일치: 컴파일 입력 전체의 일치는 아닙니다.
• 서로 다른 OS·컴파일러·SDK 세대: 라이브러리 동일성을 가정하지 않습니다.
• 매니페스트: 개별 실행 기록이므로 전체 파일 해시는 달라질 수 있습니다.

확인·조치 순서:

1. 전체 입력 지문과 컴파일러·SDK·의존성·플랫폼·실행 경로를 두 매니페스트에서 나란히 대조합니다.
2. 같은 입력 재현성 확인이 필요하면 동일한 검증된 조합으로 새 결과 폴더에 실행합니다. 기존 결과와 실패 기록은 보존합니다.
3. adapter.rs와 libadapter.rlib를 각각 비교하고 단계·의존성 전후 기록도 읽습니다. 매니페스트를 편집해 지문을 같게 만들지 않습니다.

다음 단계로 돌아갈 조건: 같은 조건의 새 실행에서 지문이 일치하면 그 OS·버전·입력 범위의 재현성으로만 기록합니다.

해결되지 않았을 때: 조건이 같은데도 다르면 두 패키지·입력·산출물 지문과 최소 실행 기록을 인계합니다. 보안 후검사 실패를 성공으로 바꾸지 않습니다.