VibePackr Enterprise · Part.3

Part.3 · Integration Helper operation

Guide connections, workflow and input/output map

First-use checkpoint and return points

Start here: A is planning before declarations. B and W1–W4 use a complete request after Part.4; these are two visits to one manual, not two separate tools.
Have ready: Use published target references and the release-compatible Helper. Architecture planning input, source-only Document and the complete synthetic request are different file roles.
Expected exercise result: Retain full-request identity and each typed status/reason/next_required_actions. Each CLI operation evaluates that full request; r2-status is not a persistent server registration query. An exit code of zero can still contain refusal.

Exercise and next steps

Open the relevant failure case

How to read numbers and file names

Part.1–8 identifies the current tool manuals. W1–W4 and codes such as GUI-01 identify exercises inside a Part. Use Case 1–5 is a separate retained procedure sequence, not the Part numbering. Case A–J and codes such as SDK-1 or IH-1 identify troubleshooting scenarios. Older filenames and pN section IDs remain valid bookmarks; read the page heading for the current Part number.

A · Before declarations: integration planning

Review the approved GAPE snapshot and published target Contract/revision. Identify the capability, required source schemas, mapping and implementation gaps, then complete the Document in Part.4. Use r2-plan-architecture only with the complete planning input supplied for that release; it differs from the Custom API request below.

Next: author declarations in Part.4

B · After declarations: validation and preparation

Put the completed Part.4 Document, target, mapping and synthetic fixture in the full request, then follow W1 below. Read the typed results of discover → normalize → validate → prepare → status; return to the affected declaration on refusal. Continue to Part.5 only when implementation is needed. Reuse an implemented integration after checking its separate registration state.

W1: begin checks with the full request · Implementation needed → Part.5

Exercise files: check the role before saving

Distinguish source-only JSON, complete requests and intentional errors. TXT files are human worksheets, not profiles, API inputs or GAPE manifests. If a file opens in the browser, save it with the correct extension and UTF-8.

Complete Custom synthetic request · read-only-custom-api.json

Before starting: file roles, paths and shell

Save the exercise files at the beginning of this manual into a fresh workspace and check their roles. TXT worksheets are human notes, not client profiles, API requests or GAPE manifests. Distinguish source-only JSON, complete requests and intentional type-error examples too.

Use bash for macOS/Linux and PowerShell for Windows. Do not copy prompts. Replace /absolute/path, C:\absolute\path and bracketed values with actual supplied values first; retain quotes. Commands using variables need the setup shell. In a new shell restore paths only, without overwriting old outputs/logs. Long code and tables scroll horizontally.

Company connection/enrollment, approval, supported Packs, published targets and approved manifests require actual supplied material at their relevant steps. Do not invent IDs, screen names or addresses. Read each W section's success and failure/return criteria, then perform one step at a time.

W1 · IH-01: start discovery from a real complete request copy

Exercise file read-only-custom-api.json is the complete synthetic envelope supplied in SDK. It illustrates the shared request shape but does not guarantee target support or normalization in your Helper release. Compare the Helper and published target first. Without a provisioned target, stop at source reading/input preparation.

Replace executable/original JSON paths below. helper-practice-01 must not already exist; the original request remains unchanged.

helper_exe="/absolute/path/packr-integration-helper"
helper_source="/absolute/path/read-only-custom-api.json"
helper_root="$HOME/helper-practice-01"
test -x "$helper_exe" && test -f "$helper_source" || exit 1
test ! -e "$helper_root" || exit 1
umask 077
mkdir -m 700 "$helper_root" || exit 1
cp "$helper_source" "$helper_root/request.json" || exit 1
helper_request="$helper_root/request.json"
"$helper_exe" r2-discover "$helper_request" > "$helper_root/01-discover.json" 2> "$helper_root/01-discover.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/01-discover.json"
cat "$helper_root/01-discover.stderr.txt"

$helperExe = 'C:\absolute\path\packr-integration-helper.exe'
$helperSource = 'C:\absolute\path\read-only-custom-api.json'
$helperRoot = Join-Path $env:USERPROFILE 'helper-practice-01'
if (!(Test-Path -LiteralPath $helperExe -PathType Leaf) -or !(Test-Path -LiteralPath $helperSource -PathType Leaf)) { throw 'Executable or full request missing' }
if (Test-Path -LiteralPath $helperRoot) { throw 'Choose a fresh practice path' }
New-Item -ItemType Directory -Path $helperRoot -ErrorAction Stop | Out-Null
$helperRequest = Join-Path $helperRoot 'request.json'
Copy-Item -LiteralPath $helperSource -Destination $helperRequest -ErrorAction Stop
$helperError = Join-Path $helperRoot '01-discover.stderr.txt'
$helperResult = Join-Path $helperRoot '01-discover.json'
& $helperExe r2-discover $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

Output field	How to read it
request_id/correlation_id	Match the complete request used
operation/lifecycle_stage	Requested stage versus actual reached stage
status/reason	Separate fields; a passed discovery can have status=PASSED and reason=NONE. DISCOVERED belongs to lifecycle_stage, not reason
next_required_actions	Array of requirements, not singular next_action
candidate_digest_sha256	Retain only when the actual stage returns a candidate digest

Important: this CLI may exit 0 while printing a typed refusal. Zero exit and file creation do not authorize the next stage. Empty/unparseable JSON requires inspecting stderr/original command and stopping at that stage. Result logs are not inputs for subsequent commands.

W2 · IH-02: do not run normalization and validation as an unchecked chain

Use the same shell as W1. In a new shell restore actual helper executable/root/request variables and inspect existing files first. Do not recreate the root or overwrite logs.

Run normalization only first:

"$helper_exe" r2-normalize "$helper_request" > "$helper_root/02-normalize.json" 2> "$helper_root/02-normalize.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/02-normalize.json"
cat "$helper_root/02-normalize.stderr.txt"

$helperResult = Join-Path $helperRoot '02-normalize.json'
$helperError = Join-Path $helperRoot '02-normalize.stderr.txt'
& $helperExe r2-normalize $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

Compare status/reason with published target/mapping. Stop on DENIED, UNKNOWN or outstanding required actions. Only after actual passage run validation:

"$helper_exe" r2-validate "$helper_request" > "$helper_root/03-validate.json" 2> "$helper_root/03-validate.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/03-validate.json"
cat "$helper_root/03-validate.stderr.txt"

$helperResult = Join-Path $helperRoot '03-validate.json'
$helperError = Join-Path $helperRoot '03-validate.stderr.txt'
& $helperExe r2-validate $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

Example branch: discovery passes but normalization returns CONTRACT_INCOMPATIBLE → stop before prepare and confirm the target revision with its owner. For required/type/unsupported-transform refusals, edit a fresh request copy. Preserve original refusal and new input/logs; recheck affected stages.

W3 · IH-03: inspect preparation and implementation requirements

Run preparation only after actual validation passage:

"$helper_exe" r2-prepare "$helper_request" > "$helper_root/04-prepare.json" 2> "$helper_root/04-prepare.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/04-prepare.json"
cat "$helper_root/04-prepare.stderr.txt"

$helperResult = Join-Path $helperRoot '04-prepare.json'
$helperError = Join-Path $helperRoot '04-prepare.stderr.txt'
& $helperExe r2-prepare $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

Read digest, reached stage, result, next requirements and any scaffold implementation need. Hand implementation needs to their owner. Only after preparation passes, to read that same request's preparation state, use:

"$helper_exe" r2-status "$helper_request" > "$helper_root/05-status.json" 2> "$helper_root/05-status.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/05-status.json"
cat "$helper_root/05-status.stderr.txt"

$helperResult = Join-Path $helperRoot '05-status.json'
$helperError = Join-Path $helperRoot '05-status.stderr.txt'
& $helperExe r2-status $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

Status describes this CLI's preparation result, not actual server registration. Use your returned digest rather than one copied from an output example. Retain 01-discover through 05-status alongside the original request digest.

W4 · IH-04: finish handover without submitting

Request/candidate: [actual digests/references]
Preparation stage: [actually returned stage]
Implementation needed: [actual result]
Registration route: [release-supplied route or not supplied]
Approval purpose/installation scope: [actual provided values]
Registration: [actual result or not performed]
Next owner: [specific responsible owner]

The first exercise does not require r2-submit. Hand over this record when trusted registration transport is missing or REQUIRES_AUTHORITY applies. Registration still does not establish binding, Work or a receipt. Repeated submissions, folder copying and copied credentials are not remedies.

More exercises and checklists

Reading sequence

Check inputs → choose a task → use the detailed first exercise/commands below → inspect results → modify/repeat → follow the relevant failure case. Part numbers are not a mandatory installation sequence; choose only needed tools.

Prerequisites and input

Compatible Helper executable, complete request, published target and supported mappings.

Both online and offline environments remain available. The optional SDK Rust set provisions SDK builds in closed on-premises environments; it is not a product default. Use actual supplied company endpoints, approval and enrollment material where an exercise needs them.

Find an exercise or case

Exercise	Task
IH-01	Inspect discovery from a complete request
IH-02	Resolve the first normalization/semantic refusal
IH-03	Distinguish candidate preparation from implementation
IH-04	Hand the exact candidate to the registration owner

Exercise IH-01 · Inspect discovery from a complete request

Open actual input and steps →

You received one supported synthetic read_quality request. Start at discovery using the full request, not a source excerpt.

Actions:

Prepare a full request.json copy matching Helper version and published target.
Inspect request_id/correlation_id/draft and definition/source/mapping/fixture.
Run r2-discover once in the fresh log directory from the first exercise below.
Record exit code separately from JSON status/reason/lifecycle_stage/next_required_actions.

Read the result: A typed discovery result, not live API connection or completed preparation.

Failure and next branch: Do not proceed on DENIED despite exit code 0. Also use DOC-2 for incomplete request/encoding issues.

Retain: Request digest/identity, product revision, discovery result and minimal original reason.

Your exercise record: fill in time, version, input reference, actual actions, observed result and next owner. Do not copy expected outcomes into an execution success record.

Exercise IH-02 · Resolve the first normalization/semantic refusal

Open actual input and steps →

Discovery PASSED while normalization refuses a target revision. Separate readable source from target compatibility.

Actions:

Run r2-normalize against the same full request and preserve its reason.
Compare published Contract/adapter/schema references and stop before prepare.
Only with actual supplied correct values, revise a new request copy and recheck affected stages.
After normalization, inspect r2-validate for required fields, types and supported transforms.

Read the result: Normalization/validation of the exact request, or an explicit unresolved target issue.

Failure and next branch: Do not guess Contract IDs/digests or reuse another release's PASS.

Retain: Original refusal, supplied target, revised request digest and new stage results.

Your exercise record: fill in time, version, input reference, actual actions, observed result and next owner. Do not copy expected outcomes into an execution success record.

Exercise IH-03 · Distinguish candidate preparation from implementation

Open actual input and steps →

Validated declarations may still produce an implementation-needed scaffold. File presence does not establish an executable adapter.

Actions:

Bind the validated full request digest and its validation.
Read candidate digest, stage, result and next requirements from r2-prepare.
If REQUIRES_IMPLEMENTATION appears, hand the required interface/scope to implementation owners.
Read r2-status for the same request without interpreting local preparation as server registration.

Read the result: A handover distinguishing prepared candidate, implementation needs and next owner.

Failure and next branch: Do not mark unsupported transforms solved by fixture changes; live API testing is separate.

Retain: Candidate digest, preparation stage, implementation needs, scope and owner.

Your exercise record: fill in time, version, input reference, actual actions, observed result and next owner. Do not copy expected outcomes into an execution success record.

Exercise IH-04 · Hand the exact candidate to the registration owner

Open actual input and steps →

Preparation is complete and operational registration is requested. The CLI may lack a trusted registration transport.

Actions:

Bind full request digest, candidate digest, purpose and customer/installation scope.
Identify the release's approval/registration owner and actual submission route.
Use submission only where supplied/authorized; hand REQUIRES_AUTHORITY over unchanged.
Record registration, binding and Work approval separately when actual product results exist.

Read the result: Exact candidate handover and actual registration state.

Failure and next branch: Do not create registration by repeated submit, credential copying or server-folder copying.

Retain: Candidate/request digests, approval purpose, submission/registration and next owner.

Your exercise record: fill in time, version, input reference, actual actions, observed result and next owner. Do not copy expected outcomes into an execution success record.

Repeat, modify and resume after failure

Preserve earlier input/version/validation/results and distinguish a new input or revision. Use fresh output paths for SDK/GAPE; retain product-returned candidate revisions for Builder. Helper commands take the same complete request rather than the preceding result. Query an existing ID first when Work is running or uncertain.

After closing a terminal, restore absolute paths and the selected environment. Recheck affected stages and hand over pending company authority, registration or approval as pending. Support records use minimal messages/shareable references, without bulk private keys, raw prompts, customer responses or full logs.

Detailed commands, inputs and troubleshooting sources

The following detailed guides share the same maintained documentation source. Use their first exercises, complete JSON, OS-specific commands, file inspection and symptom cases. Cross-Part references lead to the appropriate manual.

Full workflow and skip conditions

Integration Helper: prepare an integration without granting execution

Detailed section contents

The Helper prepares and checks a candidate. Its CLI has no trusted registration transport by itself. A PASSED discovery result does not mean a provider was called, an integration was registered, or Work was authorized. Use only the inputs and target Contract supplied for the exact release.

First preparation exercise: inspect one complete request step by step

Required: a compatible Helper executable, complete request.json and supplier-published target references. SDK and Helper are separate executables. An SDK JSON excerpt is not a complete request. Before reusing a full SDK example, verify that the Helper release supports the same target and envelope.

Preserve the supplied request and make a working copy. Confirm complete request_id, correlation_id, draft and its definition/source/mapping/fixture. Do not add real API tokens.
Replace the executable/request paths below with actual absolute paths. helper-first-01 is a fresh log directory. Run only the first command, then inspect its result.
Read stdout's status, reason, lifecycle_stage, next_required_actions and candidate digest. Do not expect a singular next_action field. This CLI can return exit code 0 while printing a typed refusal, so exit code/`$LASTEXITCODE` alone is not permission to proceed.
Only after successful discovery, run normalize → validate → prepare → status from the existing section, one step at a time against the same request copy. Do not feed the preceding result JSON into the next command; each command takes the full request.
Preserve DENIED, implementation-needed, authority-needed or unknown states and read the next actions. r2-submit is unnecessary for the first exercise. Use a new request copy and log folder when modifying inputs.

helper_exe="/absolute/path/packr-integration-helper"
helper_request="/absolute/path/request.json"
helper_logs="$HOME/helper-first-01"
test -f "$helper_exe" && test -f "$helper_request" || exit 1
test ! -e "$helper_logs" || exit 1
mkdir "$helper_logs" || exit 1
"$helper_exe" r2-discover "$helper_request" > "$helper_logs/01-discover.json" 2> "$helper_logs/01-discover.stderr.txt"
helper_exit=$?
cat "$helper_logs/01-discover.json"
cat "$helper_logs/01-discover.stderr.txt"
# Record helper_exit separately from JSON status/reason.

$helperExe = 'C:\absolute\path\packr-integration-helper.exe'
$helperRequest = 'C:\absolute\path\request.json'
$helperLogs = Join-Path $env:USERPROFILE 'helper-first-01'
if (Test-Path -LiteralPath $helperLogs) { throw 'Choose a fresh log folder' }
New-Item -ItemType Directory -Path $helperLogs -ErrorAction Stop | Out-Null
& $helperExe r2-discover $helperRequest 2> (Join-Path $helperLogs '01-discover.stderr.txt') | Out-File -LiteralPath (Join-Path $helperLogs '01-discover.json') -Encoding utf8
$helperExit = $LASTEXITCODE
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.json') -Raw -Encoding UTF8
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.stderr.txt')

These are logs, not replacement input requests. Save subsequent outputs separately as 02-normalize, 03-validate, 04-prepare and 05-status. Expected exercise outputs are stage decisions and candidate preparation records, not live API connection, registration or Work. When a published target is missing, use TARGET_NOT_PROVIDED as your progress note and keep it separate from the product's actual reason. See IH-1/2 for refusals and handover.

Inputs and ownership

Input	Owner	Check before use
Source Document or bounded MCP transcript	Customer integration owner	Supported revision and data minimization
Target Contract, capability, adapter revisions	Supplier-published release package	Exact identifiers and compatibility
Request envelope	Release procedure	Request and correlation identities, complete draft
Registration approval	Authorized product owner	Exact candidate digest, purpose, customer and installation scope

Prepare a candidate

Start with a read-only operation in a supported source format. For example, describe status.read with a service string input and service/healthy output. Do not paste a live token or customer response into the document.
Obtain the supplier-published target Contract and adapter revisions. If they are missing, record TARGET_NOT_PROVIDED; a display name that looks similar is not a valid match.
Use a complete request file supplied for your release. If the included Helper offers r2-discover, r2-normalize, r2-validate, r2-prepare, and r2-status, run those stages in that order with request.json. Preserve each status, reason, stage, and next action.
Correct only the field or mapping rejected by the actual result. The bounded example format supports primitive fields and explicit mappings; an unsupported transform or required unmapped field remains denied. A scaffold marked REQUIRES_IMPLEMENTATION still needs an adapter implementation.
Use r2-submit only in the release's authorized submission route. The CLI returns REQUIRES_AUTHORITY without trusted registration transport. Canonical registration requires a separate sealed active approval for the exact candidate and purpose. Registration still does not bind or authorize Work.

Reproducible local preparation example

If your component list includes the Helper executable and a matching complete request.json, run one stage at a time. Preserve each JSON result and read status, reason, stage, and next action before continuing; a shell exit alone is insufficient. The request needs a supported target reference from your release, not the illustrative status.read description above.

packr-integration-helper r2-discover request.json > 01-discover.json
packr-integration-helper r2-normalize request.json > 02-normalize.json
packr-integration-helper r2-validate request.json > 03-validate.json
packr-integration-helper r2-prepare request.json > 04-prepare.json
packr-integration-helper r2-status request.json > 05-status.json

Decision example: discovery can report status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED while normalization reports DENIED / CONTRACT_INCOMPATIBLE. Keep both files; stop before prepare and obtain the correct published target. Do not run all five commands blindly when an earlier typed result refuses progression.

Worked example: source accepted, target rejected

r2-discover reports status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED for a synthetic status.read document. r2-normalize then reports DENIED / CONTRACT_INCOMPATIBLE because no published target was bound. The source document is structurally accepted; the integration is not ready. Ask the supplier or integration owner for the exact target reference. Do not invent a Contract ID or change the display name until it matches by coincidence.

Worked example: candidate submitted, no registration

The validated candidate produces REQUIRES_AUTHORITY at submission. Record the candidate digest and approval purpose requested. The authorized owner must evaluate that exact candidate through the native registration path. Repeating the CLI call or adding a flag cannot turn a preparation status into registration.

Completion evidence

Preparation requires the input and target revisions, request identity, each typed result, candidate digest, unresolved gap, and next owner. A live provider connection, registration, binding, authorized Work, and receipt require separate evidence. For the source declaration, continue with Contract & Document.

A practical operational use case

For example, connect a service-status source Document to published target references. Prepare with synthetic data and inspect status, reason and next action at each stage. A normalization refusal stops progression to prepare/submit. If inputs change, record the new request revision/digest and distinguish the old refusal from the new result.

Symptom-specific checks and return to operation

Symptom or situation	Facts to check separately	Action and result to recheck
Discovery passes but normalization refuses	Source parsing versus exact target Contract/adapter revision	Obtain a published compatible target and validate the changed request from the first affected stage.
Only part of the mapping is populated	Required fields, types, supported transforms and omissions	Retain unsupported transforms as requiring implementation; edit only supported declarations.
Preparation exists without registration	Candidate digest, submission transport and exact authority purpose	Distinguish preparation from pending registration and hand over to the approved registration owner.

Minimum handover to the next owner

Handover: full request digest, source/target revisions, request/correlation IDs, typed stage results, candidate digest, scaffold implementation needs, submission/registration state and next owner. Keep live API connection tests separate from preparation results.

Read the tool-specific troubleshooting examples

These teaching examples use documented input, command and authority boundaries. Read them alongside actual product states/reasons; do not treat illustrative outcomes as execution history. Distinguish checks shared by online/offline environments from checks specific to the optional dependency route.

Worked scenario IH-1: Discovery passes but target normalization is refused

Situation: Synthetic source read_quality is discovered, but the full request references another Contract/adapter revision. Running straight through preparation would hide the first refusal.

Read these observations separately.

Discovery: status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED concerns source discovery.
Normalization: DENIED / CONTRACT_INCOMPATIBLE concerns target compatibility.
Preparation: not completed yet.

Check and action sequence:

Retain normalization status/reason/next action and stop prepare/submit.
Compare the full request with exact published targets; do not choose a merely similar label.
After obtaining supported references, retain changed request revision/digest and validate from the affected stage.

Condition for resuming: Check preparation only after that request passes normalization/semantic validation.

If still unresolved: Without a published target, hand over unavailable-target state instead of inventing IDs/digests.

Worked scenario IH-2: Preparation artifacts exist but submission requires authority

Situation: Preparation artifacts exist, but CLI submission returns REQUIRES_AUTHORITY. Copying local candidate files into server registration locations is not a remedy.

Read these observations separately.

prepare: a candidate-preparation result.
submit: requires a trusted registration route and exact authority purpose.
Work: registration, binding and execution remain separate.

Check and action sequence:

Retain candidate digest, submission result and request/correlation IDs.
Check whether the release supplies an actual registration transport and owner.
Hand over to the approved registration procedure for that candidate/purpose/customer/installation.

Condition for resuming: Record registration only from the actual registration result; confirm Work separately.

If still unresolved: Do not turn preparation into registration through repeated CLI submission or copied credentials.

Post-install tools

첫 사용 점검·복귀 지점

시작 지점: A는 선언 전 계획, B와 W1~W4는 Part.4 뒤의 전체 요청 검증입니다. 별도 도구 두 개가 아닌 같은 문서를 두 번 참조합니다.
필요한 준비물: 게시된 대상·호환 Helper를 사용합니다. 구조 계획 입력·소스 Document·전체 합성 요청은 서로 다른 파일입니다.
확인할 실습 결과: 전체 요청 신원과 각 타입 결과를 보존합니다. 명령마다 전체 요청을 평가하며 r2-status는 영구 서버 등록 조회가 아닙니다. 종료 코드 0에도 거부가 포함될 수 있습니다.

실습·다음 단계

실패 시 바로 열기

번호·파일 이름 읽는 법

Part.1~8은 현재 도구별 매뉴얼, W1~W4와 GUI-01 같은 코드는 그 안의 실습입니다. Use Case 1~5는 보존한 작업 안내 번호이며 Part 번호와 다릅니다. Case A~J와 SDK-1·IH-1 같은 코드는 문제 해결 사례입니다. 이전 파일 이름과 pN 절 주소는 기존 북마크용으로 유지하므로 현재 Part는 본문 제목으로 확인합니다.

A · 선언 전: 연동 계획

GAPE의 승인 snapshot과 게시된 대상 Contract·리비전을 먼저 확인합니다. 연결할 기능, 필요한 소스 입출력, 매핑과 구현 공백을 정리한 뒤 Part.4에서 Document를 완성합니다. r2-plan-architecture는 해당 릴리스의 완전한 계획 입력이 있을 때만 사용하며 아래 Custom API 요청과 다른 입력입니다.

다음: Part.4 선언 작성

B · 선언 후: 검증·후보 준비

Part.4에서 완성한 Document·대상·매핑·합성 fixture를 전체 요청에 넣고 아래 W1부터 단계별로 확인합니다. discover → normalize → validate → prepare → status의 타입 결과를 읽고 거부 시 해당 선언으로 돌아갑니다. 구현이 필요할 때만 Part.5로 진행합니다. 구현된 연동은 별도 등록 상태를 확인한 뒤 재사용합니다.

W1: 전체 요청으로 검증 시작 · 구현 필요 → Part.5

실습 파일: 내려받기 전에 용도 확인

JSON은 소스·전체 요청·의도적 오류 예제를 구분합니다. TXT는 사람이 채우는 양식이며 프로필·API 입력·GAPE manifest가 아닙니다. 파일이 브라우저에 열리면 다른 이름으로 저장하고 UTF-8/확장자를 확인하십시오.

전체 Custom 합성 요청 · read-only-custom-api.json

시작 전에: 파일 종류·경로·셸 확인

이 문서 첫머리의 실습 파일을 새 작업 폴더에 저장하고 역할을 확인합니다. TXT 양식은 사람이 작성하는 메모이며 앱 프로필·API 요청·GAPE manifest가 아닙니다. JSON도 소스 Document, 전체 요청, 의도적 오류 예제를 구분합니다.

macOS/Linux는 bash, Windows는 PowerShell 블록을 사용합니다. 프롬프트는 복사하지 않습니다. /absolute/path·C:\absolute\path·대괄호는 실제 제공 값으로 먼저 바꾸고 따옴표를 유지합니다. 변수가 있는 명령은 준비 절과 같은 셸에서 실행합니다. 새 셸이면 경로만 다시 지정하며 기존 결과·로그를 덮지 않습니다. 긴 코드/표는 가로 스크롤할 수 있습니다.

회사별 연결/등록·승인·지원 Pack·게시 대상·승인 manifest가 필요한 단계에서는 실제 제공 자료가 있어야 합니다. 없는 자료의 ID·화면 이름·주소를 만들어 진행하지 않습니다. 각 W 절의 정상 결과와 실패 후 복귀 기준을 모두 읽고 한 단계씩 수행합니다.

W1 · IH-01: 실제 전체 요청 사본으로 discover부터 시작

실습 파일의 read-only-custom-api.json은 SDK에 포함된 완전한 합성 envelope입니다. Helper와 같은 요청 구조를 설명하지만, 내 Helper 릴리스의 대상 지원·정규화 통과를 미리 보증하지 않습니다. 제공된 Helper와 게시 대상이 이 예제를 지원하는지 먼저 대조합니다. 게시 대상이 없으면 소스 읽기/입력 준비까지만 진행합니다.

아래 실행 파일·원본 JSON 경로를 실제 값으로 바꿉니다. helper-practice-01은 아직 없어야 하며 요청 원본을 바꾸지 않습니다.

helper_exe="/absolute/path/packr-integration-helper"
helper_source="/absolute/path/read-only-custom-api.json"
helper_root="$HOME/helper-practice-01"
test -x "$helper_exe" && test -f "$helper_source" || exit 1
test ! -e "$helper_root" || exit 1
umask 077
mkdir -m 700 "$helper_root" || exit 1
cp "$helper_source" "$helper_root/request.json" || exit 1
helper_request="$helper_root/request.json"
"$helper_exe" r2-discover "$helper_request" > "$helper_root/01-discover.json" 2> "$helper_root/01-discover.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/01-discover.json"
cat "$helper_root/01-discover.stderr.txt"

$helperExe = 'C:\absolute\path\packr-integration-helper.exe'
$helperSource = 'C:\absolute\path\read-only-custom-api.json'
$helperRoot = Join-Path $env:USERPROFILE 'helper-practice-01'
if (!(Test-Path -LiteralPath $helperExe -PathType Leaf) -or !(Test-Path -LiteralPath $helperSource -PathType Leaf)) { throw 'Executable or full request missing' }
if (Test-Path -LiteralPath $helperRoot) { throw 'Choose a fresh practice path' }
New-Item -ItemType Directory -Path $helperRoot -ErrorAction Stop | Out-Null
$helperRequest = Join-Path $helperRoot 'request.json'
Copy-Item -LiteralPath $helperSource -Destination $helperRequest -ErrorAction Stop
$helperError = Join-Path $helperRoot '01-discover.stderr.txt'
$helperResult = Join-Path $helperRoot '01-discover.json'
& $helperExe r2-discover $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

결과에서 읽을 칸	읽는 방법
request_id·correlation_id	사용한 전체 요청과 같은지
operation·lifecycle_stage	지금 요청한 단계와 실제 도달 단계
status·reason	별도 필드입니다. 발견 통과 예시는 status=PASSED·reason=NONE이며 DISCOVERED는 reason이 아닌 lifecycle_stage 값입니다
next_required_actions	다음 요구사항 배열; 단일 next_action 필드가 아님
candidate_digest_sha256	해당 단계가 실제 후보 지문을 반환했을 때만 보관

중요: 이 CLI는 타입 거부 JSON을 출력하면서 종료 코드가 0일 수 있습니다. 종료 코드 0과 파일 생성만으로 다음 단계에 가지 않습니다. JSON이 비었거나 파싱할 수 없으면 stderr와 원래 명령을 확인하고 그 단계에서 중지합니다. 로그 파일은 다음 명령의 요청으로 재사용하지 않습니다.

W2 · IH-02: normalize와 validate를 한 번에 붙여 실행하지 않기

W1의 변수가 남아 있는 같은 셸입니다. 새 셸이면 실제 helper_exe, helper_root, helper_request 또는 PowerShell 변수를 다시 지정하고 기존 파일부터 확인합니다. 기존 root를 다시 만들거나 로그를 덮지 않습니다.

먼저 normalize만:

"$helper_exe" r2-normalize "$helper_request" > "$helper_root/02-normalize.json" 2> "$helper_root/02-normalize.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/02-normalize.json"
cat "$helper_root/02-normalize.stderr.txt"

$helperResult = Join-Path $helperRoot '02-normalize.json'
$helperError = Join-Path $helperRoot '02-normalize.stderr.txt'
& $helperExe r2-normalize $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

status/reason과 게시된 대상·매핑을 대조합니다. DENIED·UNKNOWN·필수 조치가 남으면 여기서 멈춥니다. 실제 통과가 확인된 경우에만 다음 validate를 실행합니다.

"$helper_exe" r2-validate "$helper_request" > "$helper_root/03-validate.json" 2> "$helper_root/03-validate.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/03-validate.json"
cat "$helper_root/03-validate.stderr.txt"

$helperResult = Join-Path $helperRoot '03-validate.json'
$helperError = Join-Path $helperRoot '03-validate.stderr.txt'
& $helperExe r2-validate $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

예시 분기: 발견 통과 → 정규화 CONTRACT_INCOMPATIBLE이면 prepare를 실행하지 않고 대상 리비전을 담당자와 확인합니다. required·타입·미지원 변환 거부면 해당 선언을 새 요청 사본에서 수정합니다. 원래 거부와 새 사본·새 로그를 보존하고 영향받은 단계부터 검사합니다.

W3 · IH-03: prepare 출력과 구현 필요를 직접 읽기

validate의 실제 통과를 확인한 뒤에만 아래 prepare를 수행합니다.

"$helper_exe" r2-prepare "$helper_request" > "$helper_root/04-prepare.json" 2> "$helper_root/04-prepare.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/04-prepare.json"
cat "$helper_root/04-prepare.stderr.txt"

$helperResult = Join-Path $helperRoot '04-prepare.json'
$helperError = Join-Path $helperRoot '04-prepare.stderr.txt'
& $helperExe r2-prepare $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

후보 지문, 실제 단계, result, 다음 요구사항과 scaffold의 구현 필요 여부를 읽습니다. 구현 필요면 해당 담당자에게 인계합니다. prepare가 통과한 같은 요청의 준비 상태를 읽을 때만 다음 status를 사용합니다.

"$helper_exe" r2-status "$helper_request" > "$helper_root/05-status.json" 2> "$helper_root/05-status.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/05-status.json"
cat "$helper_root/05-status.stderr.txt"

$helperResult = Join-Path $helperRoot '05-status.json'
$helperError = Join-Path $helperRoot '05-status.stderr.txt'
& $helperExe r2-status $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

status는 이 CLI의 준비 결과입니다. 서버에 실제 등록됐다는 뜻이 아닙니다. 출력 예시의 후보 지문을 복사해 기록하지 말고 내 결과의 실제 값을 사용합니다. 01-discover부터 05-status까지 각 파일과 원본 요청 지문을 묶어 보관합니다.

W4 · IH-04: 제출하지 않고도 준비 인계를 완성하기

요청/후보: [실제 지문과 참조]
준비 단계: [실제 반환 단계]
구현 필요: [실제 결과]
등록 경로: [릴리스가 제공한 경로 또는 미제공]
승인 목적·설치 범위: [실제 제공 값]
등록: [실제 결과 또는 미수행]
다음 담당자: [정확한 담당자]

첫 실습에는 r2-submit이 필요하지 않습니다. 신뢰된 등록 전송 경로가 없거나 REQUIRES_AUTHORITY라면 위 기록으로 인계합니다. 실제 등록 결과가 생겨도 바인딩·Work·영수증은 각각 별도입니다. 반복 제출·폴더 복사·자격 증명 복사를 해결책으로 쓰지 않습니다.

추가 용례·체크리스트

이 Part를 읽는 순서

준비물 확인 → 목적에 맞는 용례 선택 → 뒤의 첫 실습·실제 명령 수행 → 결과 읽기 → 수정·반복 → 실패 시 해당 사례로 이동합니다. 숫자 순서가 모든 도구의 필수 설치 순서는 아닙니다. 필요한 도구만 선택하십시오.

시작 조건과 입력

버전이 맞는 Helper 실행 파일, 전체 요청과 게시된 대상·지원 매핑.

온라인과 오프라인을 모두 사용할 수 있습니다. SDK의 선택 Rust 의존성 세트는 폐쇄형 온프렘의 SDK 빌드용이며 전체 제품의 기본값이 아닙니다. 회사별 endpoint·승인·등록 자료가 필요한 용례는 실제 제공 자료를 사용합니다.

실습과 사례 찾아보기

용례	해볼 일
IH-01	전체 요청으로 발견 결과 읽기
IH-02	정규화·의미 검증의 첫 거부 해결
IH-03	후보 준비와 구현 필요를 구분
IH-04	등록 담당자에게 정확한 후보 인계

용례 IH-01 · 전체 요청으로 발견 결과 읽기

실제 입력·단계 열기 →

지원되는 합성 read_quality 요청 한 건을 받았습니다. 소스 발췌를 전체 요청으로 착각하지 않고 발견 단계부터 시작합니다.

진행 순서:

Helper 실행 파일 버전과 게시 대상에 맞는 전체 request.json 사본을 준비합니다.
request_id/correlation_id/draft와 definition/source/mapping/fixture를 확인합니다.
아래 첫 실습의 새 로그 폴더에서 r2-discover를 한 번 실행합니다.
종료 코드와 JSON status/reason/lifecycle_stage/next_required_actions를 각각 기록합니다.

결과를 이렇게 읽습니다: 소스 발견에 대한 타입 결과입니다. 실제 API 연결이나 전체 준비 완료는 아닙니다.

실패·다음 분기: 종료 코드 0이어도 DENIED면 후속 단계로 가지 않습니다. 전체 요청/인코딩 오류는 DOC-2도 확인합니다.

남길 기록: 요청 지문·신원, 제품 리비전, 발견 결과와 원문 최소 사유.

내 연습 기록: 수행 시각·버전·입력 참조·실제로 한 단계·관찰 결과·다음 담당자를 채우십시오. 예시에 적힌 기대 결과를 그대로 성공 기록에 복사하지 않습니다.

용례 IH-02 · 정규화·의미 검증의 첫 거부 해결

실제 입력·단계 열기 →

발견은 PASSED지만 대상 리비전이 맞지 않아 정규화가 거부됩니다. 소스가 읽혔다는 사실과 대상 호환을 분리합니다.

진행 순서:

같은 전체 요청으로 r2-normalize를 실행하고 현재 사유를 보존합니다.
게시된 Contract·어댑터·스키마와 요청 참조를 대조하고 prepare로 넘기지 않습니다.
제공된 올바른 값이 실제 있을 때만 새 요청 사본을 수정하고 영향받은 단계부터 검사합니다.
정규화 후 r2-validate의 required·타입·지원 변환 판정을 확인합니다.

결과를 이렇게 읽습니다: 정확한 요청의 정규화·검증 결과 또는 명시적인 미해결 대상 문제입니다.

실패·다음 분기: Contract ID·지문을 추측하거나 다른 릴리스의 PASS를 재사용하지 않습니다.

남길 기록: 원래 거부, 제공 대상, 변경 요청 지문, 새 단계별 결과.

용례 IH-03 · 후보 준비와 구현 필요를 구분

실제 입력·단계 열기 →

선언은 검증됐지만 생성 scaffold에 구현 필요가 표시될 수 있습니다. 파일 존재만으로 실행 가능한 어댑터라고 판단하지 않습니다.

진행 순서:

검증된 전체 요청의 지문과 검증 결과를 고정합니다.
r2-prepare 결과에서 후보 지문·단계·result와 다음 요구사항을 읽습니다.
REQUIRES_IMPLEMENTATION 표시가 있으면 구현 담당자에게 필요한 인터페이스·범위만 인계합니다.
r2-status로 같은 요청의 현재 준비 결과를 읽되 실제 서버 등록 상태로 해석하지 않습니다.

결과를 이렇게 읽습니다: 준비 후보·미구현 요구·다음 담당자가 구분된 인계입니다.

실패·다음 분기: 미지원 변환은 입력값만 바꿔 해결됐다고 표시하지 않습니다. 실제 API 호출 시험도 별도입니다.

남길 기록: 후보 지문·준비 단계·구현 필요·지원 범위·담당자.

용례 IH-04 · 등록 담당자에게 정확한 후보 인계

실제 입력·단계 열기 →

준비가 끝났고 운영 등록을 요청하려 합니다. CLI에는 신뢰된 등록 전송 경로가 없을 수 있습니다.

진행 순서:

전체 요청 지문·후보 지문·목적·고객/설치 범위를 묶습니다.
릴리스가 제공한 승인·등록 담당자와 실제 제출 경로를 확인합니다.
제출이 제공되고 승인된 경우에만 사용하며 REQUIRES_AUTHORITY는 그대로 인계합니다.
등록 결과·바인딩·Work 승인은 각각 실제 제품 결과가 생겼을 때 따로 기록합니다.

결과를 이렇게 읽습니다: 정확한 후보의 준비 인계와 등록의 실제 상태까지입니다.

실패·다음 분기: 반복 submit·자격 증명 복사·서버 폴더 직접 복사로 등록을 만들지 않습니다.

남길 기록: 후보/요청 지문, 승인 목적, 제출/등록 상태, 다음 담당자.

반복 사용·수정·실패 후 재개

이전 입력·버전·검증·결과를 보존하고 새 입력 또는 새 리비전을 구분합니다. SDK/GAPE 파일 출력은 새 경로를 쓰고, Builder는 제품이 반환한 새 후보 리비전을 기록합니다. Helper는 단계 결과를 다음 명령의 입력으로 바꾸지 않고 같은 전체 요청을 사용합니다. 진행 중이거나 결과가 불명확한 Work는 먼저 기존 ID로 조회합니다.

터미널을 닫았다면 절대 경로와 선택 환경을 다시 지정합니다. 실제 변경의 영향을 받는 단계부터 재확인하고, 회사별 권한·등록·승인이 미완료이면 그 상태로 인계합니다. 지원에는 최소 메시지와 공개 가능한 참조를 사용하며 비밀키·원문 프롬프트·고객 응답·전체 로그를 일괄 전달하지 않습니다.

상세 명령·입력 예제·문제 해결 원본

아래에는 이 Part에 해당하는 기존 상세 안내를 같은 작성 원본에서 이어 싣습니다. 첫 실습, 전체 JSON, OS별 명령, 실제 결과 파일 확인과 증상별 상세 사례를 필요할 때 펼쳐 읽으십시오. 다른 Part의 사례를 참조하는 링크도 해당 매뉴얼로 연결됩니다.

전체 흐름·생략 조건

Integration Helper: 실행 권한 없이 연동 후보 준비

상세 절 목차

Helper는 후보를 준비하고 검사합니다. CLI만으로는 신뢰된 등록 전송 경로가 없습니다. 발견 단계의 PASSED는 제공자 호출·연동 등록·Work 승인을 뜻하지 않습니다. 정확한 릴리스가 제공한 입력과 대상 Contract만 사용하십시오.

첫 준비 실습: 전체 요청 한 건을 단계별로 읽기

준비물: 버전이 맞는 Helper 실행 파일, 완전한 request.json, 공급자가 게시한 대상 참조. SDK와 Helper는 별도 실행 파일입니다. SDK의 발췌 JSON만 저장해 이 요청을 대신하지 않습니다. SDK 전체 예제를 재사용하려면 그 Helper 릴리스에서도 동일한 대상·envelope를 지원하는지 먼저 확인합니다.

제공된 요청 원본을 보존하고 작업용 사본을 만듭니다. request_id, correlation_id, draft 전체와 그 안의 definition/source/mapping/fixture를 확인합니다. 실제 API 토큰은 넣지 않습니다.
아래 실행 파일·요청 경로를 실제 절대 경로로 바꿉니다. helper-first-01은 새 로그 폴더입니다. 첫 명령만 실행하고 결과를 읽습니다.
stdout의 status, reason, lifecycle_stage, next_required_actions, 후보 지문을 확인합니다. next_action이라는 단일 필드가 있다고 가정하지 않습니다. 이 CLI는 타입 거부 결과를 출력하면서 종료 코드 0일 수 있으므로 `$LASTEXITCODE`/종료 코드만으로 다음 단계에 가지 않습니다.
발견이 통과한 경우에만 기존 절의 normalize → validate → prepare → status를 각각 같은 요청 사본으로 실행합니다. 이전 명령의 JSON 결과를 다음 명령의 입력으로 바꾸지 않습니다. 각 명령은 전체 요청을 받습니다.
DENIED, 구현 필요, 권한 필요 또는 모르는 상태면 해당 결과를 보존하고 다음 조치를 읽습니다. 첫 연습에 r2-submit은 필요하지 않습니다. 요청을 수정할 때는 새 사본·새 로그 폴더를 사용합니다.

helper_exe="/absolute/path/packr-integration-helper"
helper_request="/absolute/path/request.json"
helper_logs="$HOME/helper-first-01"
test -f "$helper_exe" && test -f "$helper_request" || exit 1
test ! -e "$helper_logs" || exit 1
mkdir "$helper_logs" || exit 1
"$helper_exe" r2-discover "$helper_request" > "$helper_logs/01-discover.json" 2> "$helper_logs/01-discover.stderr.txt"
helper_exit=$?
cat "$helper_logs/01-discover.json"
cat "$helper_logs/01-discover.stderr.txt"
# helper_exit와 JSON의 status/reason을 별도로 기록합니다.

$helperExe = 'C:\absolute\path\packr-integration-helper.exe'
$helperRequest = 'C:\absolute\path\request.json'
$helperLogs = Join-Path $env:USERPROFILE 'helper-first-01'
if (Test-Path -LiteralPath $helperLogs) { throw 'Choose a fresh log folder' }
New-Item -ItemType Directory -Path $helperLogs -ErrorAction Stop | Out-Null
& $helperExe r2-discover $helperRequest 2> (Join-Path $helperLogs '01-discover.stderr.txt') | Out-File -LiteralPath (Join-Path $helperLogs '01-discover.json') -Encoding utf8
$helperExit = $LASTEXITCODE
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.json') -Raw -Encoding UTF8
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.stderr.txt')

위 파일은 로그이며 그 자체를 새 요청으로 제출하지 않습니다. 후속 결과도 02-normalize, 03-validate, 04-prepare, 05-status처럼 구분해 저장합니다. 예상 연습 결과는 단계 판정과 후보 준비 기록이며 실제 API 연결·등록·Work가 아닙니다. 게시된 대상이 없다면 TARGET_NOT_PROVIDED는 담당자의 진행 기록으로 쓰고, 제품이 실제 출력한 reason과 구분하십시오. 아래 IH-1/2에서 거부와 인계 예를 확인합니다.

입력과 담당자

입력	담당자	사용 전 확인
소스 Document 또는 제한된 MCP 기록	고객 연동 담당자	지원 리비전·데이터 최소화
대상 Contract·기능·어댑터 리비전	공급자가 게시한 릴리스 패키지	정확한 식별자·호환성
요청 envelope	릴리스 절차	요청·상관관계 신원과 완전한 draft
등록 승인	권한 있는 제품 담당자	정확한 후보 지문·목적·고객·설치 범위

후보 준비

지원되는 소스 형식으로 읽기 전용 작업부터 설명합니다. 예: status.read의 입력 service 문자열과 출력 service·healthy. 실제 토큰이나 고객 응답은 문서에 붙여넣지 않습니다.
공급자가 게시한 대상 Contract·어댑터 리비전을 확보합니다. 없으면 TARGET_NOT_PROVIDED로 기록하십시오. 비슷해 보이는 표시 이름은 유효한 대상 매칭이 아닙니다.
해당 릴리스가 제공한 완전한 요청 파일을 사용합니다. 포함된 Helper가 r2-discover, r2-normalize, r2-validate, r2-prepare, r2-status를 제공한다면 request.json으로 이 순서대로 진행합니다. 매 단계의 상태·사유·다음 조치를 보존하십시오.
실제 결과가 거부한 필드 또는 매핑만 고칩니다. 제한된 예시 형식은 기본 자료형과 명시적 매핑을 지원합니다. 지원되지 않는 변환이나 매핑되지 않은 필수 필드는 계속 거부됩니다. REQUIRES_IMPLEMENTATION scaffold에는 실제 어댑터 구현이 추가로 필요합니다.
릴리스의 승인된 제출 경로에서만 r2-submit을 사용합니다. 신뢰된 등록 전송 경로가 없는 CLI는 REQUIRES_AUTHORITY를 반환합니다. 정식 등록에는 정확한 후보·목적에 묶인 별도의 유효한 승인이 필요합니다. 등록되어도 Work 바인딩·승인이 자동으로 생기지 않습니다.

재현 가능한 로컬 준비 예시

전달 목록에 Helper 실행 파일과 버전에 맞는 완전한 request.json이 있다면 아래 단계를 하나씩 실행합니다. 각 JSON에서 status·reason·단계·다음 조치를 읽고 진행하십시오. 셸 종료 코드만으로 통과를 판단하지 않습니다. 요청에는 위의 status.read 설명 대신 릴리스가 제공한 지원 대상 참조가 필요합니다.

packr-integration-helper r2-discover request.json > 01-discover.json
packr-integration-helper r2-normalize request.json > 02-normalize.json
packr-integration-helper r2-validate request.json > 03-validate.json
packr-integration-helper r2-prepare request.json > 04-prepare.json
packr-integration-helper r2-status request.json > 05-status.json

판정 예시: 발견 결과가 status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED라도 정규화가 DENIED / CONTRACT_INCOMPATIBLE을 반환할 수 있습니다. 두 결과를 모두 보존하고 prepare 전에 멈춰 게시된 올바른 대상을 확보하십시오. 앞 단계가 거부됐는데 다섯 명령을 무조건 연속 실행하지 마십시오.

예시: 소스는 통과, 대상은 거부

합성 status.read 문서에 대해 r2-discover가 status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED를 반환합니다. 게시된 대상이 묶이지 않아 r2-normalize는 DENIED / CONTRACT_INCOMPATIBLE을 반환합니다. 소스 문서 구조는 받아들여졌지만 연동은 준비되지 않았습니다. 공급자 또는 연동 담당자에게 정확한 대상 참조를 요청하십시오. Contract ID를 임의로 만들거나 표시 이름만 맞춰 통과시키지 않습니다.

예시: 후보 제출 후 등록되지 않음

검증된 후보의 제출 결과가 REQUIRES_AUTHORITY입니다. 후보 지문과 요청한 승인 목적을 기록합니다. 권한 담당자가 정확한 후보를 native 등록 경로에서 평가해야 합니다. CLI 반복 실행이나 옵션 추가로 준비 상태를 등록으로 바꿀 수 없습니다.

완료 증거

입력·대상 리비전, 요청 신원, 단계별 타입 결과, 후보 지문, 미해결 문제와 다음 담당자가 기록되면 준비 단계가 끝납니다. 실제 제공자 연결·등록·바인딩·승인된 Work·영수증에는 각각 별도 증거가 필요합니다. 소스 선언은 Contract & Document를 참고하십시오.

단계별 실제 사용 용례

예를 들어 서비스 상태를 읽는 소스 Document와 공급자가 게시한 대상 참조를 연결합니다. 첫 시도는 합성 데이터로 준비하고 단계마다 상태·사유·다음 조치를 읽습니다. 정규화가 거부되면 그 뒤 prepare·submit으로 넘기지 않습니다. 입력을 고쳤다면 요청 리비전과 지문을 새로 기록하여 이전 거부와 새 결과를 구별합니다.

증상별 확인과 복귀 확인

증상 또는 상황	분리해서 확인할 사실	조치와 다시 확인할 결과
발견 PASS 뒤 정규화 거부	소스 파싱 결과와 정확한 대상 Contract·어댑터 리비전	게시된 호환 대상을 확인하고 변경된 요청을 처음 영향을 받는 단계부터 검증합니다.
필드 매핑이 일부만 채워짐	required 목록·타입·지원 변환과 누락된 필드	미지원 변환은 구현 필요 상태로 보존하고 지원 범위의 선언만 수정합니다.
prepare 결과는 있으나 등록은 없음	후보 지문·제출 경로·정확한 승인 목적	준비 완료와 등록 대기를 구분하고 승인된 등록 담당자에게 인계합니다.

다음 담당자에게 넘길 최소 기록

인계 항목: 전체 요청 지문, 소스·대상 리비전, 요청·상관관계 ID, 각 단계의 타입 결과, 후보 지문, scaffold의 구현 필요 여부, 제출·등록 상태와 다음 담당자. 실제 API 연결 시험은 준비 결과와 구분합니다.

도구별 문제 해결 사례 읽기

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

상세 예시 IH-1: 발견은 통과했지만 대상 정규화가 거부됨

상황: 합성 소스 Document의 read_quality는 발견됐지만 전체 요청은 다른 Contract·어댑터 리비전을 가리킵니다. 발견 PASS 뒤 prepare까지 무조건 실행하면 첫 거부를 놓칩니다.

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

발견: status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED는 소스 발견 결과입니다.
정규화: DENIED / CONTRACT_INCOMPATIBLE은 대상 호환 거부입니다.
후보 준비: 아직 완료되지 않았습니다.

확인·조치 순서:

정규화의 상태·사유·다음 조치를 보존하고 후속 prepare·submit을 멈춥니다.
공급자가 게시한 정확한 대상과 전체 요청의 참조를 대조합니다. 이름만 비슷한 대상을 고르지 않습니다.
지원되는 참조를 확보한 뒤 수정 요청의 리비전·지문을 보관하고 영향을 받은 단계부터 검사합니다.

다음 단계로 돌아갈 조건: 해당 요청이 정규화·의미 검증을 통과한 뒤에만 후보 준비 결과를 확인합니다.

해결되지 않았을 때: 게시된 대상이 없으면 ID·스키마 지문을 만들어 맞추지 않고 대상 미제공으로 인계합니다.

상세 예시 IH-2: prepare 산출물은 있지만 제출이 권한을 요구함

상황: 후보 준비 결과가 만들어졌지만 CLI 제출은 REQUIRES_AUTHORITY를 반환합니다. 로컬 후보 파일을 서버 등록 위치에 복사하면 해결되는 문제가 아닙니다.

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

prepare: 후보 준비 결과입니다.
submit: 신뢰된 등록 경로·정확한 승인 목적을 요구합니다.
Work: 등록·바인딩·실행은 별도입니다.

확인·조치 순서:

후보 지문과 제출 결과·요청·상관관계 ID를 보존합니다.
해당 릴리스가 실제 등록 전송 경로와 담당자를 제공하는지 확인합니다.
정확한 후보·목적·고객·설치 범위에 대한 승인된 등록 절차로 인계합니다.

다음 단계로 돌아갈 조건: 등록 담당자의 실제 결과를 확인한 경우에만 등록으로 기록하고 Work는 따로 확인합니다.

해결되지 않았을 때: CLI 반복 제출이나 자격 증명 복사로 준비 상태를 등록 상태로 바꾸지 않습니다.

설치 후 도구 목록

Local documentation edition. Company connection, approval and enrollment require actual supplied material. Educational scenarios are not customer execution evidence. Apple signing/notarization and customer activation/delivery remain held.

Connect the Guides and Parts 1–8

Choose a purpose in a Guide, then use the relevant Part for exact tool steps. The same sequence, vocabulary and artifact roles apply in both.

Purpose-to-manual map with a textual alternative below.

Purpose guides

Common PoC Guide
Choose a question, collect scoped observations and review the result. A retained-reading route needs no new installation.
Google Reviewer Guide
Bind the exact review delivery and criterion evidence. Cloud access, document coverage and actual Google approval remain separate.
On-premises Guide
Prepare the exact OS, package, network choice and toolchain. Use the local SDK shortcut only after its prerequisites are supplied.
Custom Execution Guide
Choose a supported task. Keep source-document preparation, full SDK candidates and actual Work/report inspection as distinct routes.
Guide links open the public website and require network access; this offline manual and its local examples remain readable without it.

Recommended integration order and shortcuts

Helper B checks the completed declarations before you decide whether implementation or a new Pack is needed. After an implementation or declaration change, repeat only the affected supported checks and finish the separate implementation/registration/Pack approval path before operation. A generated candidate grants no operating authority.

Select only the route needed for your goal. Retained PoC reading can begin without installation. A supplied local SDK exercise uses Part.1 → Part.5 and does not require a new GAPE scan or appliance account. An existing approved Pack can use Part.1 → Part.7 → Part.8 after its current prerequisites are checked. New integration/Pack authoring follows the full conditional sequence.

Part map and tool responsibilities

Part	Role and expected boundary
Part.1 · Installation and first connection	OS preparation, supplied packages and first connection. Installation is not an executed Work.
Part.2 · GAPE observation, comparison and sharing	Revision-bound architecture observation. A worksheet is not the approved GAPE input manifest.
Part.3 · Integration Helper operation	A plans before the Document; B checks the completed full request. Each stage reads its typed status/reason.
Part.4 · Contract and Document authoring	Author the source Document and mappings; use the supplied target Contract/revision. JSON syntax alone does not establish semantic compatibility.
Part.5 · SDK Engine practice and candidates	Generate a local SDK implementation candidate. Reuse an implemented, registered, release-compatible integration when it already meets the need.
Part.6 · Builder and Additional Packs	Prepare a Pack candidate when a new Pack is needed. Reuse an existing approved Pack that meets the goal and installation scope.
Part.7 · PackrGUI and headless operation	Use the supplied GUI/headless route under its current authority and preconditions. Inspect the returned Work identity and result.
Part.8 · Operations, troubleshooting and support	Compare same-Work artifacts, receipt and closure; keep human acceptance pending until actually recorded.

Shared vocabulary

Guide / Part: A Guide is a purpose/role route; a Part is a tool reference. They complement each other and are not two competing numbered workflows.
Contract / source Document: The published target Contract defines the supported target and revision. The source Document declares your source shapes. A source declaration does not authorize execution.
Complete request / source-only file: A complete SDK request includes request_id, correlation_id and draft with definition/source/mapping/fixture. The source-only status Document is one component, not that complete request.
Fixture / actual observation: A fixture supplies synthetic values for a declared local exercise. Its declared fields do not prove a real provider call, current connectivity or a customer result.
SDK candidate / Pack candidate: The SDK candidate has README.md, adapter.rs, libadapter.rlib and manifest.json. A Builder Pack candidate is a separate product-returned candidate with its own validation/approval path. Neither automatically becomes an approved Pack.
Worksheet / receipt / acceptance: A worksheet records a human note. A receipt is a product execution record. PASSED validation and automation completion can coexist with human acceptance pending; record each field at its actual scope.
Online / Offline: These are setup choices. Offline product development requires the exact declared dependency set and native tools; an offline manual ZIP only supports document reading.

Match each input to the right output

The status.read source-only example and the read_quality SDK exercise are different examples. Use a matching complete request; do not pass the status source file directly as the quality SDK request. Expected mapping values below are teaching expectations, not a newly captured run.

File / role	Input	Output / check
`status-document.json` Source-only CUSTOM_API declaration for status.read. Use it inside the complete supplied preparation request.	service: string	Declared service: string and healthy: boolean. This is a schema, not an observed service response.
`read-only-custom-api.json / custom-api-01.json` The complete maintained SDK base request; the guide copy is byte-equivalent JSON.	fixture.response.component = "fixture-component"; score = "97" (string)	STRING_TO_INTEGER maps score to expected integer quality_score 97. The documented SDK result is a local candidate.
`custom-api-02.json` A complete second SDK request changing only the two fixture response values.	component = "my-test-component"; score = "88" (string)	Expected mapped component is "my-test-component" and quality_score is integer 88. Inspect actual manifest/stages; identical mapping source is possible.
`custom-api-score-number.json` Intentional negative input, not a successful base example.	fixture.response.score = 88 (JSON number) against a declared string schema	Keep the actual typed failure result. Do not convert the example into a claimed successful candidate.
`Worksheet / SDK artifacts / Work reports` Three different artifact classes: human notes, local compiled candidate, actual Work/report/receipt records.	Use the matching tool and current target; never submit a worksheet or previous result as the next full request.	Bind outputs to the actual input, version, candidate or Work identity. File presence and exit 0 alone are insufficient.

Integration roles and operating boundaries

User-provided architecture overview. Tool panels explain complementary roles rather than a mandatory execution order. The original Legacy SDK planned/release-specific wording remains in the image; use Part.5 and the exact supplied package for current SDK availability. This figure grants no authority and is not runtime proof. The displayed edition is an English SVG with current documentation updates; the earlier raster original remains preserved.

Open the full-size SVG illustration

가이드와 Part.1–8 연결

가이드에서 목적을 고른 뒤 해당 Part에서 정확한 도구 단계를 확인합니다. 두 문서는 같은 순서·용어·자료 역할을 사용합니다.

목적별 가이드

PoC 공통 가이드
질문을 정하고 범위에 맞는 관찰을 모아 결과를 검토합니다. 보존 기록 독해에는 신규 설치가 필요하지 않습니다.
Google 심사자 가이드
정확한 심사 전달물과 기준 증거를 연결합니다. Cloud 접근·문서 범위·실제 Google 승인은 각각 구분합니다.
온프레미스 가이드
정확한 OS·패키지·네트워크 선택·도구 체인을 준비합니다. 로컬 SDK 준비 요건이 제공된 뒤에만 해당 단축 경로를 사용합니다.
Custom Execution 가이드
지원 작업을 선택합니다. 소스 문서 준비·전체 SDK 후보·실제 Work 및 보고서 확인을 서로 다른 경로로 구분합니다.
가이드 링크는 네트워크가 필요한 공개 웹사이트를 엽니다. 이 오프라인 매뉴얼과 로컬 예제는 네트워크 없이 읽을 수 있습니다.

권장 연동 순서와 단축 경로

Helper B는 구현·새 Pack 필요 여부를 결정하기 전에 완성된 선언을 확인합니다. 구현·선언 변경 후에는 영향을 받은 지원 검사를 다시 수행하고 별도 구현·등록·Pack 승인 경로를 마친 뒤 사용합니다. 생성 후보는 운영 권한을 부여하지 않습니다.

목표에 필요한 경로만 선택합니다. 보존 PoC 독해는 설치 없이 시작할 수 있습니다. 제공된 로컬 SDK 실습은 Part.1 → Part.5를 따르며 새 GAPE 관찰·어플라이언스 계정이 필요하지 않습니다. 기존 승인 Pack은 현재 준비 요건 확인 후 Part.1 → Part.7 → Part.8을 따를 수 있습니다. 새 연동·Pack 작성은 조건부 전체 순서를 따릅니다.

Part 연결과 도구 역할

Part	역할과 기대 범위
Part.1 · 설치·초기 연결	OS 준비·제공 패키지·초기 연결입니다. 설치는 실행된 Work가 아닙니다.
Part.2 · GAPE 관찰·비교·공유	리비전에 고정된 구조 관찰입니다. 워크시트는 승인된 GAPE 입력 매니페스트가 아닙니다.
Part.3 · Integration Helper 사용	A는 Document 작성 전 계획, B는 완성된 전체 요청 확인입니다. 단계마다 타입이 있는 status·reason을 읽습니다.
Part.4 · Contract·Document 작성	소스 Document·매핑을 작성하고 제공된 대상 Contract·리비전을 사용합니다. JSON 구문만으로 의미상 호환성이 확인되지 않습니다.
Part.5 · SDK Engine 실습·연동 후보	로컬 SDK 구현 후보를 생성합니다. 기존 구현·등록·릴리스 호환 연동이 요구를 충족하면 재사용합니다.
Part.6 · Builder·추가 Pack 사용	새 Pack이 필요할 때 Pack 후보를 준비합니다. 목표·설치 범위에 맞는 기존 승인 Pack은 재사용합니다.
Part.7 · PackrGUI·헤드리스 사용	현재 권한·사전 조건에 따라 제공 GUI·헤드리스 경로를 사용합니다. 반환된 Work 식별·결과를 확인합니다.
Part.8 · 운영·문제 해결·지원	동일 Work 산출물·영수증·종결을 비교하며 사람 인수은 실제 기록될 때까지 대기로 유지합니다.

공통 용어

가이드 / Part: 가이드는 목적·역할 경로이고 Part는 도구 설명입니다. 서로 보완하며 경쟁하는 두 번호 순서가 아닙니다.
Contract / 소스 Document: 게시된 대상 Contract는 지원 대상·리비전을 정합니다. 소스 Document는 소스 형식을 선언합니다. 소스 선언은 실행을 승인하지 않습니다.
전체 요청 / 소스 전용 파일: 전체 SDK 요청은 request_id·correlation_id와 definition·source·mapping·fixture가 있는 draft를 포함합니다. status 소스 Document는 한 구성 요소이며 전체 요청이 아닙니다.
Fixture / 실제 관찰: fixture는 선언된 로컬 실습의 합성 값을 제공합니다. 선언 필드는 실제 공급자 호출·현재 연결·고객 결과를 입증하지 않습니다.
SDK 후보 / Pack 후보: SDK 후보에는 README.md·adapter.rs·libadapter.rlib·manifest.json이 있습니다. Builder Pack 후보는 별도 제품 반환 후보이며 자체 검증·승인 경로를 가집니다. 어느 쪽도 자동으로 승인 Pack이 되지 않습니다.
워크시트 / 영수증 / 인수: 워크시트는 사람 기록입니다. 영수증은 제품 실행 기록입니다. 검증 PASSED·자동화 완료와 사람 인수 대기는 함께 존재할 수 있으며 각 필드의 실제 범위를 기록합니다.
Online / Offline: 구성 선택 사항입니다. Offline 제품 개발에는 정확한 선언 의존성 세트·네이티브 도구가 필요하며 오프라인 매뉴얼 ZIP은 문서 열람을 지원합니다.

입력별 올바른 출력 연결

status.read 소스 전용 예제와 read_quality SDK 실습은 서로 다른 예제입니다. 일치하는 전체 요청을 사용하고 status 소스 파일을 quality SDK 전체 요청으로 제출하지 않습니다. 아래 매핑 값은 설명을 위한 기대값이며 새 실행 캡처가 아닙니다.

파일 / 역할	입력	출력 / 확인
`status-document.json` status.read의 소스 전용 CUSTOM_API 선언입니다. 제공된 전체 준비 요청 안에서 사용합니다.	service: string	service: string·healthy: boolean을 선언합니다. 스키마이며 관찰된 서비스 응답이 아닙니다.
`read-only-custom-api.json / custom-api-01.json` 유지관리되는 전체 SDK 기준 요청이며 가이드 사본은 같은 JSON입니다.	fixture.response.component = "fixture-component"; score = "97" (문자열)	STRING_TO_INTEGER는 score를 기대 정수 quality_score 97로 매핑합니다. 문서의 SDK 결과는 로컬 후보입니다.
`custom-api-02.json` fixture 응답 값 두 개만 바꾼 두 번째 전체 SDK 요청입니다.	component = "my-test-component"; score = "88" (문자열)	기대 매핑 component는 "my-test-component", quality_score는 정수 88입니다. 실제 매니페스트·단계를 확인하며 매핑 소스는 같을 수 있습니다.
`custom-api-score-number.json` 정상 기준 예제가 아닌 의도적 오류 입력입니다.	선언된 문자열 스키마에 fixture.response.score = 88 (JSON 숫자) 사용	실제 타입 오류 결과를 보존하며 이 예제를 성공 후보로 기록하지 않습니다.
`Worksheet / SDK artifacts / Work reports` 사람 기록·로컬 컴파일 후보·실제 Work 및 보고서·영수증이라는 서로 다른 산출물 종류입니다.	해당 도구·현재 타깃을 사용하며 워크시트·이전 결과를 다음 전체 요청으로 제출하지 않습니다.	실제 입력·버전·후보 또는 Work 식별에 출력을 연결합니다. 파일 존재·종료 0만으로는 충분하지 않습니다.

연동 역할과 운영 범위

사용자가 제공한 구조 개요입니다. 도구 패널은 필수 실행 순서가 아닌 상호 보완 역할을 설명합니다. 원본의 Legacy SDK planned·릴리스별 문구는 유지되며 현재 SDK 가용성은 Part.5와 실제 제공 패키지로 확인합니다. 이 그림은 권한·런타임 증거가 아닙니다. 현재 표시본은 문서 변경을 반영한 영문 SVG이며, 이전 래스터 원본은 보존합니다.

SVG 그림 원본 크기로 열기