VibePackr Enterprise · Part.2
Part.2 · GAPE observation, comparison and sharing
Guide connections, workflow and input/output map
First-use checkpoint and return points
- Start here
- Begin with W1 when a viewer is supplied. Use W2 only if you have the executable, approved manifest and its readable source revisions.
- Have ready
- The observation worksheet is not a manifest. Keep viewer and required adjacent data files together; preserve the supplied directory layout.
- Expected exercise result
- For viewer review: one recorded node/edge/revision and limits. For a new scan: the tool-created output set and a successful snapshot validation result. Neither proves live runtime connectivity.
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.
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.
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 · GAPE-01: begin by reading a supplied viewer
Reviewers without source access or manifests can begin with a supplied viewer/snapshot. gape-observation-worksheet.txt is a note, not a manifest.
- Open the inventory's viewer HTML through the browser's open-file action. Compare the local file and supplied version.
- Read snapshot ID, source revision and disclosure class. Use browser Find or the viewer's supplied selection feature for a node name.
- Record one node, relationship direction and observation source. Static relationships are separate from runtime connectivity.
- Record out-of-scope, filter and unresolved limitations too. Missing search results do not establish capability absence.
Human output example: Selected node=[actual display] / relationship=[actual direction] / revision=[displayed value] / runtime validation=not performed. For missing files request the exact missing viewer/data path from delivery support; redact private paths in external support.
W2 · GAPE-02: create a snapshot from an approved manifest
This procedure is for an owner supplied with all three: executable, approved manifest and readable referenced source. The eight example files do not include an approved GAPE manifest. A source Document/worksheet is not a substitute.
Replace paths and prepare only the output parent. The tool creates final gape-observation-first-01 itself.
gape_exe="/absolute/path/packr-gape"
gape_manifest="/absolute/path/approved-manifest.json"
gape_output="$HOME/gape-observation-first-01"
test -x "$gape_exe" && test -f "$gape_manifest" || exit 1
test ! -e "$gape_output" || exit 1
"$gape_exe" snapshot "$gape_manifest" "$gape_output" || exit 1
"$gape_exe" validate-snapshot "$gape_output/gape-architecture-snapshot.json" || exit 1
ls -la "$gape_output"$gapeExe = 'C:\absolute\path\packr-gape.exe'
$gapeManifest = 'C:\absolute\path\approved-manifest.json'
$gapeOutput = Join-Path $env:USERPROFILE 'gape-observation-first-01'
if (!(Test-Path -LiteralPath $gapeExe -PathType Leaf) -or !(Test-Path -LiteralPath $gapeManifest -PathType Leaf)) { throw 'Executable or manifest missing' }
if (Test-Path -LiteralPath $gapeOutput) { throw 'Choose a fresh output path' }
& $gapeExe snapshot $gapeManifest $gapeOutput
if ($LASTEXITCODE -ne 0) { throw 'Snapshot failed' }
& $gapeExe validate-snapshot (Join-Path $gapeOutput 'gape-architecture-snapshot.json')
if ($LASTEXITCODE -ne 0) { throw 'Validation failed' }
Get-ChildItem -LiteralPath $gapeOutputSnapshot stdout reports ID, node/edge/finding counts and execution_authority: NONE. Successful validate-snapshot stdout is the snapshot ID, not necessarily a PASS word. Retain both exit code and original output.
gape-observation-first-01/
gape-input-manifest.json
gape-architecture-snapshot.json
gape-projection-snapshot.json
gape-projection-authority.json
gape-projection-drift.json
gape-architecture-drift.json
gape-architecture-viewer.html
gape-public-safe-viewer.html
gape-public-safe-data.jsonThis is the referenced CLI's base output set; supplied navigation extensions may add files. After failure, partial output is not validated output. Preserve original error and failed stage.
W3 · GAPE-03: compare before/after through the same procedure
Keep W2's executable variables in the same shell, or restore actual gape_exe/$gapeExe in a new shell. Bind before/after to actual snapshot JSON files.
gape_before="/absolute/path/before/gape-architecture-snapshot.json"
gape_after="/absolute/path/after/gape-architecture-snapshot.json"
"$gape_exe" validate-snapshot "$gape_before" || exit 1
"$gape_exe" validate-snapshot "$gape_after" || exit 1
"$gape_exe" compare "$gape_before" "$gape_after" || exit 1$gapeBefore = 'C:\absolute\path\before\gape-architecture-snapshot.json'
$gapeAfter = 'C:\absolute\path\after\gape-architecture-snapshot.json'
& $gapeExe validate-snapshot $gapeBefore
if ($LASTEXITCODE -ne 0) { throw 'Before snapshot invalid' }
& $gapeExe validate-snapshot $gapeAfter
if ($LASTEXITCODE -ne 0) { throw 'After snapshot invalid' }
& $gapeExe compare $gapeBefore $gapeAfter
if ($LASTEXITCODE -ne 0) { throw 'Comparison failed' }Check sequence: both snapshot IDs/revisions/scopes → individual structural validation → reported changes/unknowns → separately established runtime impact. An omitted node under a different scope is not a removed capability. Do not compare after either validation fails. Resume once both inputs and comparison scope are confirmed.
W4 · GAPE-04: separate sharing files from originals
| File kind | Retain/use | Before sharing |
|---|---|---|
| Input manifest, full snapshot, engineering viewer | Approved engineering environment | May include internal source/paths |
| PUBLIC_SAFE viewer/data | Release-approved sharing scope | Confirm classification, recipient and purpose |
| Worksheet | Minimal observation note | Remove sensitive paths/identifiers |
A PUBLIC_SAFE filename does not grant new publication authority. Hold sharing for unconfirmed classification. Check that the shareable copy retains matching snapshot/revision/limits, and do not use it as execution/approval evidence.
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
Approved snapshot/viewer, or GAPE executable/approved manifest/readable source revision.
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 |
|---|---|
| GAPE-01 | Read one relationship in a supplied snapshot |
| GAPE-02 | Create an observation from approved input |
| GAPE-03 | Compare observations at two revisions |
| GAPE-04 | Hand over an approved sharing projection |
Exercise GAPE-01 · Read one relationship in a supplied snapshot
A design reviewer received an approved viewer rather than source code. Practice reading observation scope without product execution.
Actions:
- Check viewer/snapshot version and disclosure class, then open it in a browser.
- Select one node and read name, relationship direction and observation source.
- Note snapshot ID, source revision and static/dynamic observation limits.
- Separate the observation from questions requiring the Contract or its owner.
Read the result: You can describe the observed relationship, revision and unconfirmed scope.
Failure and next branch: Use GAPE-2 for nodes hidden by filters; do not conclude capability absence.
Retain: Snapshot/revision/node/relationship/limits/follow-up question.
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 GAPE-02 · Create an observation from approved input
An owner with read access and an approved manifest creates a snapshot of a specified committed revision.
Actions:
- Bind executable, manifest and fresh output paths using the first exercise below.
- Check referenced source/revision availability, then run snapshot.
- Run validate-snapshot on the generated JSON and retain stdout/finding count/validation.
- Open the generated viewer/snapshot and match ID/revision.
Read the result: A scoped observation and structural validation record, not runtime validation.
Failure and next branch: Choose a new name for existing output; hand missing approved source to its owner.
Retain: Manifest digest, revision, command/output path, snapshot/validation.
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 GAPE-03 · Compare observations at two revisions
Review whether relationships changed after an integration. Comparing an old picture with new source names is insufficient.
Actions:
- Preserve both snapshots, manifests, revisions and scopes.
- Validate each snapshot using the supplied check and record scope differences.
- Use the supported compare command or both viewers to separate changed relationships from out-of-scope items.
- Retain STALE/UNRESOLVED and hand runtime-impact questions to the relevant owner.
Read the result: A review of observed differences and comparison limits across two revisions.
Failure and next branch: Do not treat scope-related omissions as removed capability or edit diagrams to match.
Retain: Both snapshot IDs/revisions/scopes, changes, unknowns 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 GAPE-04 · Hand over an approved sharing projection
Explain relationship structure to a partner. An engineering viewer may contain private source paths.
Actions:
- Identify recipient/purpose and the release-approved disclosure class.
- Check whether an approved PUBLIC_SAFE projection is supplied; do not send internal originals.
- Check retained snapshot/revision/limits in the shareable copy and explain node meaning.
- Bind it only to the review question, without asserting execution/registration/approval.
Read the result: An approved-scope observation explanation with source reference.
Failure and next branch: Hold sharing if classification is unconfirmed; deleting a few paths does not create an approved projection.
Retain: Recipient scope, purpose, projection class, snapshot and limits.
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
GAPE: inspect a revision-bound architecture observation
GAPE: inspect a revision-bound architecture observation
Detailed section contents
First observation exercise: prepare, run and open results
Inspect what you received first. If you received only an approved snapshot and viewer, open the supplied HTML viewer in a browser, read snapshot ID/source revision/disclosure class and select one node. You do not need new source or a new manifest. An owner with an executable and approved manifest can run the local exercise below. A source Document or SDK input.json is not a GAPE manifest.
Select the executable and a fresh output path
Replace gape_exe/$gapeExe and gape_manifest/$gapeManifest with the actual executable and approved manifest's absolute paths. The manifest's source paths and revision must exist too. Prepare only the output parent, leaving gape-observation-01 absent. Do not expand the source scope by guessing paths.
gape_exe="/absolute/path/packr-gape"
gape_manifest="/absolute/path/approved-manifest.json"
gape_output="$HOME/gape-observation-01"
test -f "$gape_exe" && test -f "$gape_manifest" || exit 1
test ! -e "$gape_output" || exit 1
"$gape_exe" snapshot "$gape_manifest" "$gape_output" || exit 1
"$gape_exe" validate-snapshot "$gape_output/gape-architecture-snapshot.json" || exit 1
ls -la "$gape_output"$gapeExe = 'C:\absolute\path\packr-gape.exe'
$gapeManifest = 'C:\absolute\path\approved-manifest.json'
$gapeOutput = Join-Path $env:USERPROFILE 'gape-observation-01'
if (!(Test-Path -LiteralPath $gapeExe -PathType Leaf) -or !(Test-Path -LiteralPath $gapeManifest -PathType Leaf)) { throw 'Executable or approved manifest missing' }
if (Test-Path -LiteralPath $gapeOutput) { throw 'Choose a fresh output path' }
& $gapeExe snapshot $gapeManifest $gapeOutput
if ($LASTEXITCODE -ne 0) { throw 'Snapshot failed' }
& $gapeExe validate-snapshot (Join-Path $gapeOutput 'gape-architecture-snapshot.json')
if ($LASTEXITCODE -ne 0) { throw 'Snapshot validation failed' }
Get-ChildItem -LiteralPath $gapeOutputWhat to read: snapshot stdout contains snapshot ID, node/edge/finding counts and execution_authority: NONE. Do not assume zero findings. Preserve validation and actual generated files. Open the included viewer if supplied; otherwise read snapshot JSON in an editor. Do not guess an HTML filename.
Short exercise: record one node's name, source revision, relationship and observation limits. To compare snapshots preserve both originals and check whether the release supports compare before.json after.json. Do not infer behavior outside observation. Keep engineering snapshots internal and use an approved PUBLIC_SAFE projection for external sharing.
If blocked: missing executable → installation preparation; missing source path/revision → approved-input preparation; failed snapshot validation → observation validation. Continue with GAPE-1/2 below; do not invent a manifest to expand scope.
When to use it
Use GAPE when an integration owner needs to understand which component and interface a proposed operation depends on. Check that the exact release provides the GAPE tool and an approved input manifest. A general source folder, screenshot, or architecture infographic is not a manifest.
Prepare the observation
- Record the approved source revision, folders to inspect, exclusions, expected rules, and sharing level. GAPE observes the selected saved revision; unsaved edits and live runtime behavior may be outside that result.
- If your component list includes
packr-gapeand an approved manifest, runpackr-gape snapshot manifest.json new-output-folderwith a new output folder. Otherwise ask for the supported observation procedure. - Validate the generated snapshot with
packr-gape validate-snapshot gape-architecture-snapshot.jsonwhen that command is supplied. Validation checks the snapshot's structure and provenance, not actual runtime behavior. - Open the approved offline viewer. Start with one node and relationship, note its source revision and observation limitation, then compare it with the independent expected Contract or owner rule. Keep
UNRESOLVEDorSTALEas findings; do not promote them to consistent by editing the viewer. - Share only the PUBLIC_SAFE projection where allowed. Keep engineering input, internal paths, source ranges, and finding explanations inside the approved engineering environment.
Command example for a release that actually supplies GAPE
Use the commands below only when your installation includes packr-gape and an approved manifest for a source tree you are allowed to inspect. The output directory must be new. validate-snapshot checks the snapshot, not the running appliance.
packr-gape snapshot approved-manifest.json new-observation-folder
packr-gape validate-snapshot new-observation-folder/gape-architecture-snapshot.jsonUse the filename actually emitted by your release if it differs from this example; record the manifest digest, source revisions, snapshot ID, validation result, and execution_authority: NONE. If the binary or approved manifest is absent, stop this path and record not supplied for this release.
Worked example: a diagram appears to prove an adapter
An operator sees a relationship between PackrGUI and an integration adapter in a GAPE snapshot. The relationship is STATIC_SOURCE; the current customer runtime may use another feature configuration, and a dynamic call may be outside the saved source observation. Record the exact source version shown in the snapshot and ask the integration owner for the supplied Contract and connection evidence. Do not write “connected” or “authorized” in a deployment record.
Worked example: observation and expectation disagree
The snapshot contains an interface association but the expected owner rule is missing or bound to a different revision. GAPE reports UNRESOLVED or STALE. Preserve the manifest identity, snapshot digest, finding, and exact revision. The responsible owner reconciles the Contract and source separately; refreshing a graphic is not a repair.
Completion evidence
The observation is complete when the manifest, snapshot validation result, selected projection, revision, disclosure class, limitations, and any unresolved findings are recorded. Integration registration or Work remains a separate path. Continue with Integration Helper or the Contract & Document guide.
A practical operational use case
Before a new integration, an owner may need to understand which components handle data. Pin the stored revision in the approved manifest and trace one node and its relations. Record provenance and unobserved dynamic paths; when comparing another document, retain both revisions. The diagram alone does not establish a runtime incident cause.
Symptom-specific checks and return to operation
| Symptom or situation | Facts to check separately | Action and result to recheck |
|---|---|---|
| The source changed but the old snapshot is open | Snapshot time, source revision and manifest digest | Observe approved new inputs into a fresh location and distinguish the earlier snapshot. |
| A node is not visible | Manifest scope, exclusions, supported language and viewer filters | Check scope and record out-of-scope or unconfirmed; do not infer capability absence. |
| A proposed share contains private paths | Projection classification and approved export | Stop sharing and check for an approved PUBLIC_SAFE projection; retain detailed engineering output internally. |
Minimum handover to the next owner
Handover: source revision, manifest and snapshot digests, observation scope, disclosure class, selected nodes/relations, unresolved items and next owner. Keep snapshot validation separate from runtime evidence.
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 GAPE-1: Reviewing an old snapshot after source changes
Situation: A diagram reported as inconsistent belongs to an earlier stored revision. First distinguish current source, approved manifest and observation revisions.
Read these observations separately.
- Diagram: has a specific snapshot ID/source revision.
- Current source: unsaved changes may be outside observation.
- Validation: snapshot structure checks are not runtime validation.
Check and action sequence:
- Compare manifest digest, snapshot creation time and exact stored revision.
- For a new observation, use approved inputs/supplied commands and fresh output.
- Retain both observations and identify changed relations/limits.
Condition for resuming: Continue scoped observation review when the intended revision matches a validated snapshot.
If still unresolved: With an unconfirmed manifest/revision, retain unconfirmed observation rather than editing the diagram to match.
Worked scenario GAPE-2: A node is hidden by filters or outside observation scope
Situation: A search finds no component and a user assumes absence. Filters, manifest exclusions and supported language can limit visibility/observation.
Read these observations separately.
- No search result: an outcome for the selected view scope.
- Manifest: defines observed folders and exclusions.
- Implementation absence: not established by this view alone.
Check and action sequence:
- Check search/filter settings and the original observation’s scope/revision/exclusions.
- Request an authorized observation for another scope; do not add private data to a public view.
- Distinguish out-of-scope, view filtering and unconfirmed state, then hand source questions to the owner.
Condition for resuming: Cite only relations confirmed for that revision/scope.
If still unresolved: Do not label it unimplemented/absent without source support.
첫 사용 점검·복귀 지점
- 시작 지점
- 뷰어가 있으면 W1부터 읽습니다. 실행 파일·승인 manifest·해당 소스가 있을 때만 W2를 수행합니다.
- 필요한 준비물
- 관찰 양식은 manifest가 아닙니다. 뷰어·인접 데이터 파일을 함께 두고 제공된 폴더 구조를 유지합니다.
- 확인할 실습 결과
- 뷰어 검토는 노드·관계·리비전·한계 기록, 신규 관찰은 출력 파일과 snapshot 검증 결과가 필요합니다. 둘 다 실제 런타임 연결 증거는 아닙니다.
실습·다음 단계
실패 시 바로 열기
번호·파일 이름 읽는 법
Part.1~8은 현재 도구별 매뉴얼, W1~W4와 GUI-01 같은 코드는 그 안의 실습입니다. Use Case 1~5는 보존한 작업 안내 번호이며 Part 번호와 다릅니다. Case A~J와 SDK-1·IH-1 같은 코드는 문제 해결 사례입니다. 이전 파일 이름과 pN 절 주소는 기존 북마크용으로 유지하므로 현재 Part는 본문 제목으로 확인합니다.
실습 파일: 내려받기 전에 용도 확인
JSON은 소스·전체 요청·의도적 오류 예제를 구분합니다. TXT는 사람이 채우는 양식이며 프로필·API 입력·GAPE manifest가 아닙니다. 파일이 브라우저에 열리면 다른 이름으로 저장하고 UTF-8/확장자를 확인하십시오.
시작 전에: 파일 종류·경로·셸 확인
이 문서 첫머리의 실습 파일을 새 작업 폴더에 저장하고 역할을 확인합니다. TXT 양식은 사람이 작성하는 메모이며 앱 프로필·API 요청·GAPE manifest가 아닙니다. JSON도 소스 Document, 전체 요청, 의도적 오류 예제를 구분합니다.
macOS/Linux는 bash, Windows는 PowerShell 블록을 사용합니다. 프롬프트는 복사하지 않습니다. /absolute/path·C:\absolute\path·대괄호는 실제 제공 값으로 먼저 바꾸고 따옴표를 유지합니다. 변수가 있는 명령은 준비 절과 같은 셸에서 실행합니다. 새 셸이면 경로만 다시 지정하며 기존 결과·로그를 덮지 않습니다. 긴 코드/표는 가로 스크롤할 수 있습니다.
회사별 연결/등록·승인·지원 Pack·게시 대상·승인 manifest가 필요한 단계에서는 실제 제공 자료가 있어야 합니다. 없는 자료의 ID·화면 이름·주소를 만들어 진행하지 않습니다. 각 W 절의 정상 결과와 실패 후 복귀 기준을 모두 읽고 한 단계씩 수행합니다.
W1 · GAPE-01: 제공된 뷰어부터 읽는 첫 연습
소스 권한이나 매니페스트가 없는 검토자는 받은 뷰어·snapshot으로 시작할 수 있습니다. gape-observation-worksheet.txt는 기록 양식이며 manifest가 아닙니다.
- 제공 목록에 적힌 뷰어 HTML을 브라우저의 파일 열기로 엽니다. 주소창의 로컬 파일과 받은 버전을 대조합니다.
- snapshot ID·소스 리비전·공유 등급을 읽습니다. 브라우저 찾기로 노드 이름을 찾거나 제공 뷰어의 선택 기능을 씁니다.
- 노드 하나와 관계 방향, 관찰 출처를 worksheet에 적습니다. 정적 관계는 실제 런타임 연결과 구분합니다.
- 관찰 밖·필터·미해결 표시를 함께 적습니다. 검색 결과가 없다는 이유만으로 기능이 없다고 쓰지 않습니다.
사람용 출력 예: 선택 노드=[실제 표시] / 관계=[실제 방향] / 리비전=[표시된 값] / 런타임 검증=미수행. 파일이 없으면 뷰어/부속 데이터의 실제 누락 경로를 전달 담당자에게 요청합니다. 내부 경로를 외부 지원 요청에 그대로 넣지 않습니다.
W2 · GAPE-02: 승인 manifest로 새 snapshot 만들기
아래는 실행 파일과 승인 매니페스트, 그 안의 읽기 가능한 소스가 모두 제공된 담당자의 절차입니다. 예제 파일 8개에는 GAPE 승인 manifest가 없습니다. 소스 Document·worksheet를 그 대신 넣지 않습니다.
경로를 실제 값으로 바꾸고 출력의 부모 폴더만 준비합니다. gape-observation-first-01 최종 폴더는 도구가 만듭니다.
gape_exe="/absolute/path/packr-gape"
gape_manifest="/absolute/path/approved-manifest.json"
gape_output="$HOME/gape-observation-first-01"
test -x "$gape_exe" && test -f "$gape_manifest" || exit 1
test ! -e "$gape_output" || exit 1
"$gape_exe" snapshot "$gape_manifest" "$gape_output" || exit 1
"$gape_exe" validate-snapshot "$gape_output/gape-architecture-snapshot.json" || exit 1
ls -la "$gape_output"$gapeExe = 'C:\absolute\path\packr-gape.exe'
$gapeManifest = 'C:\absolute\path\approved-manifest.json'
$gapeOutput = Join-Path $env:USERPROFILE 'gape-observation-first-01'
if (!(Test-Path -LiteralPath $gapeExe -PathType Leaf) -or !(Test-Path -LiteralPath $gapeManifest -PathType Leaf)) { throw 'Executable or manifest missing' }
if (Test-Path -LiteralPath $gapeOutput) { throw 'Choose a fresh output path' }
& $gapeExe snapshot $gapeManifest $gapeOutput
if ($LASTEXITCODE -ne 0) { throw 'Snapshot failed' }
& $gapeExe validate-snapshot (Join-Path $gapeOutput 'gape-architecture-snapshot.json')
if ($LASTEXITCODE -ne 0) { throw 'Validation failed' }
Get-ChildItem -LiteralPath $gapeOutputsnapshot 명령은 ID·노드 수·관계 수·finding 수·execution_authority: NONE을 표시합니다. validate-snapshot 성공 stdout은 snapshot ID입니다. PASS라는 단어를 반드시 찾는 검사가 아닙니다. 종료 코드와 원문을 함께 남깁니다.
gape-observation-first-01/
gape-input-manifest.json
gape-architecture-snapshot.json
gape-projection-snapshot.json
gape-projection-authority.json
gape-projection-drift.json
gape-architecture-drift.json
gape-architecture-viewer.html
gape-public-safe-viewer.html
gape-public-safe-data.json위는 현재 문서가 참조하는 CLI의 기본 출력 구성입니다. navigation 확장이 제공되면 추가 파일이 있을 수 있습니다. 실패하면 출력 일부가 있어도 결과를 검증 완료로 보지 말고 원문 오류와 실패 stage를 보존합니다.
W3 · GAPE-03: 이전/현재 snapshot을 같은 절차로 비교하기
W2의 실행 파일 변수가 같은 셸에 남아 있어야 합니다. 새 셸이면 실제 gape_exe/$gapeExe를 다시 지정합니다. before/after에는 실제 생성된 두 JSON을 지정합니다.
gape_before="/absolute/path/before/gape-architecture-snapshot.json"
gape_after="/absolute/path/after/gape-architecture-snapshot.json"
"$gape_exe" validate-snapshot "$gape_before" || exit 1
"$gape_exe" validate-snapshot "$gape_after" || exit 1
"$gape_exe" compare "$gape_before" "$gape_after" || exit 1$gapeBefore = 'C:\absolute\path\before\gape-architecture-snapshot.json'
$gapeAfter = 'C:\absolute\path\after\gape-architecture-snapshot.json'
& $gapeExe validate-snapshot $gapeBefore
if ($LASTEXITCODE -ne 0) { throw 'Before snapshot invalid' }
& $gapeExe validate-snapshot $gapeAfter
if ($LASTEXITCODE -ne 0) { throw 'After snapshot invalid' }
& $gapeExe compare $gapeBefore $gapeAfter
if ($LASTEXITCODE -ne 0) { throw 'Comparison failed' }확인 순서: 두 snapshot의 ID·리비전·입력 범위 → 각각의 구조 검사 → 비교가 표시한 변화/미해결 → 실제 실행 영향의 별도 확인 순서입니다. 범위가 달라 관찰되지 않은 노드를 삭제된 기능이라고 쓰지 않습니다. 한 snapshot 검사가 실패하면 compare로 넘어가지 않습니다. 복귀는 두 입력의 유효성과 비교 범위가 확인됐을 때입니다.
W4 · GAPE-04: 공유할 파일을 원본과 구분하기
| 파일 종류 | 보관/사용 | 보내기 전 확인 |
|---|---|---|
| 입력 manifest·전체 snapshot·엔지니어링 뷰어 | 승인된 엔지니어링 환경 | 내부 소스/경로를 포함할 수 있음 |
| PUBLIC_SAFE 뷰어·데이터 | 해당 릴리스가 승인한 공유 범위 | 실제 공개 등급·수신자·목적 |
| worksheet | 최소 관찰 기록 | 민감한 경로·식별자 제거 |
PUBLIC_SAFE라는 이름만으로 새 공개 승인이 생기는 것은 아닙니다. 공유 등급이 미확인이면 보류하고 담당자에게 확인합니다. 공유본에서 같은 snapshot·리비전·관찰 한계를 읽을 수 있는지 확인하고, 그 자료를 실행·승인의 증거로 사용하지 않습니다.
추가 용례·체크리스트
이 Part를 읽는 순서
준비물 확인 → 목적에 맞는 용례 선택 → 뒤의 첫 실습·실제 명령 수행 → 결과 읽기 → 수정·반복 → 실패 시 해당 사례로 이동합니다. 숫자 순서가 모든 도구의 필수 설치 순서는 아닙니다. 필요한 도구만 선택하십시오.
시작 조건과 입력
승인 snapshot/뷰어 또는 GAPE 실행 파일·승인 manifest·읽기 가능한 소스 리비전.
온라인과 오프라인을 모두 사용할 수 있습니다. SDK의 선택 Rust 의존성 세트는 폐쇄형 온프렘의 SDK 빌드용이며 전체 제품의 기본값이 아닙니다. 회사별 endpoint·승인·등록 자료가 필요한 용례는 실제 제공 자료를 사용합니다.
실습과 사례 찾아보기
| 용례 | 해볼 일 |
|---|---|
| GAPE-01 | 제공 snapshot에서 관계 한 개 읽기 |
| GAPE-02 | 승인 입력으로 새 관찰 생성 |
| GAPE-03 | 두 리비전의 관찰 비교 |
| GAPE-04 | 내부 관찰을 공유용 자료로 인계 |
용례 GAPE-01 · 제공 snapshot에서 관계 한 개 읽기
설계 검토자는 소스 코드 대신 승인된 뷰어를 받았습니다. 이 연습은 제품 실행 없이 관찰 범위를 읽는 연습입니다.
진행 순서:
- 받은 뷰어·snapshot의 버전과 공유 등급을 확인하고 브라우저에서 엽니다.
- 노드 하나를 선택해 표시 이름·관계 방향·관찰 출처를 읽습니다.
- snapshot ID·소스 리비전·정적/동적 관찰 한계를 메모합니다.
- 질문과 관련된 Contract/담당자에게 확인할 항목을 관찰과 분리해 적습니다.
결과를 이렇게 읽습니다: 어떤 리비전의 어떤 관계를 읽었는지와 미확인 범위를 설명할 수 있습니다.
실패·다음 분기: 필터 때문에 안 보이는 노드는 아래 GAPE-2 사례로 분류하며 기능 부재로 결론 내리지 않습니다.
남길 기록: snapshot·리비전·노드·관계·관찰 한계·후속 질문.
내 연습 기록: 수행 시각·버전·입력 참조·실제로 한 단계·관찰 결과·다음 담당자를 채우십시오. 예시에 적힌 기대 결과를 그대로 성공 기록에 복사하지 않습니다.
용례 GAPE-02 · 승인 입력으로 새 관찰 생성
읽기 권한과 승인 매니페스트를 가진 담당자가 정해진 저장 리비전의 새 snapshot을 만듭니다.
진행 순서:
- 아래 첫 실습의 실행 파일·매니페스트·새 출력 경로를 실제 값으로 지정합니다.
- 매니페스트가 가리키는 소스와 리비전이 존재하는지 확인하고 snapshot 명령을 실행합니다.
- 생성 JSON에 validate-snapshot을 수행하고 stdout·finding 수·검사 결과를 보존합니다.
- 실제 생성된 뷰어와 snapshot을 열어 같은 ID·리비전을 확인합니다.
결과를 이렇게 읽습니다: 범위가 고정된 관찰과 구조 검사가 기록됩니다. 런타임 실행 검증은 아닙니다.
실패·다음 분기: 출력 폴더가 이미 있으면 새 이름을 고릅니다. 승인 소스가 없으면 입력 담당자에게 인계합니다.
남길 기록: 매니페스트 지문, 리비전, 명령·출력 위치, snapshot·검사 결과.
내 연습 기록: 수행 시각·버전·입력 참조·실제로 한 단계·관찰 결과·다음 담당자를 채우십시오. 예시에 적힌 기대 결과를 그대로 성공 기록에 복사하지 않습니다.
용례 GAPE-03 · 두 리비전의 관찰 비교
새 연동 뒤 관계가 바뀌었는지 검토합니다. 이전 그림과 새 소스의 이름만 비교하지 않습니다.
진행 순서:
- 이전/현재 snapshot과 각각의 매니페스트·리비전·관찰 범위를 보존합니다.
- 각 snapshot을 해당 제공 검사로 검증하고 범위 차이가 있는지 적습니다.
- 릴리스가 지원하는 compare 명령 또는 두 뷰어로 관계 변화와 관찰 밖 항목을 분리합니다.
- STALE/UNRESOLVED는 그대로 남기고 실제 실행 영향은 별도 담당자가 확인하도록 인계합니다.
결과를 이렇게 읽습니다: 두 리비전의 관찰 차이와 비교 한계를 설명하는 검토 기록입니다.
실패·다음 분기: 서로 다른 범위 때문에 사라진 노드를 삭제된 기능으로 단정하거나 그림을 수정해 일치시키지 않습니다.
남길 기록: 두 snapshot ID/리비전/범위, 변화·미확인·담당자.
내 연습 기록: 수행 시각·버전·입력 참조·실제로 한 단계·관찰 결과·다음 담당자를 채우십시오. 예시에 적힌 기대 결과를 그대로 성공 기록에 복사하지 않습니다.
용례 GAPE-04 · 내부 관찰을 공유용 자료로 인계
파트너에게 관계 개요를 설명해야 합니다. 내부 엔지니어링 뷰어는 비공개 소스 경로를 포함할 수 있습니다.
진행 순서:
- 수신자와 공유 목적을 확인하고 릴리스가 승인한 공개 등급을 확인합니다.
- 승인된 PUBLIC_SAFE 투영이 제공되는지 확인합니다. 내부 원본 파일을 임의로 전달하지 않습니다.
- 공유본에도 snapshot·리비전·관찰 한계가 남는지 읽고 노드 의미를 설명합니다.
- 실행·등록·승인을 증명하는 자료로 사용하지 않고 해당 검토 질문에만 연결합니다.
결과를 이렇게 읽습니다: 승인 범위에 맞는 관찰 설명 자료와 출처 참조입니다.
실패·다음 분기: 공개 등급이 미확인이면 공유를 보류합니다. 경로 몇 개를 지운 원본을 승인된 투영으로 간주하지 않습니다.
남길 기록: 수신 범위·공유 목적·투영 등급·snapshot·검토 한계.
내 연습 기록: 수행 시각·버전·입력 참조·실제로 한 단계·관찰 결과·다음 담당자를 채우십시오. 예시에 적힌 기대 결과를 그대로 성공 기록에 복사하지 않습니다.
반복 사용·수정·실패 후 재개
이전 입력·버전·검증·결과를 보존하고 새 입력 또는 새 리비전을 구분합니다. SDK/GAPE 파일 출력은 새 경로를 쓰고, Builder는 제품이 반환한 새 후보 리비전을 기록합니다. Helper는 단계 결과를 다음 명령의 입력으로 바꾸지 않고 같은 전체 요청을 사용합니다. 진행 중이거나 결과가 불명확한 Work는 먼저 기존 ID로 조회합니다.
터미널을 닫았다면 절대 경로와 선택 환경을 다시 지정합니다. 실제 변경의 영향을 받는 단계부터 재확인하고, 회사별 권한·등록·승인이 미완료이면 그 상태로 인계합니다. 지원에는 최소 메시지와 공개 가능한 참조를 사용하며 비밀키·원문 프롬프트·고객 응답·전체 로그를 일괄 전달하지 않습니다.
상세 명령·입력 예제·문제 해결 원본
아래에는 이 Part에 해당하는 기존 상세 안내를 같은 작성 원본에서 이어 싣습니다. 첫 실습, 전체 JSON, OS별 명령, 실제 결과 파일 확인과 증상별 상세 사례를 필요할 때 펼쳐 읽으십시오. 다른 Part의 사례를 참조하는 링크도 해당 매뉴얼로 연결됩니다.
전체 흐름·생략 조건
GAPE: 리비전에 묶인 아키텍처 관찰 검토
GAPE: 리비전에 묶인 아키텍처 관찰 검토
상세 절 목차
첫 관찰 실습: 입력 준비, 실행, 결과 열기
먼저 받은 파일을 확인합니다. 승인된 snapshot과 뷰어만 받은 사람은 제공된 HTML 뷰어를 브라우저에서 열어 snapshot ID·소스 리비전·공개 등급을 읽고 노드 하나를 선택합니다. 소스나 매니페스트를 새로 만들 필요가 없습니다. 실행 파일과 승인 manifest를 받은 담당자는 아래 로컬 관찰을 진행할 수 있습니다. 일반 소스 Document나 SDK input.json을 GAPE 매니페스트로 사용하지 않습니다.
실행할 파일과 새 출력 경로 지정
gape_exe/$gapeExe는 제공된 실행 파일, manifest/$gapeManifest는 실제 승인 매니페스트의 절대 경로로 바꿉니다. 그 매니페스트가 지정한 소스 위치와 리비전도 존재해야 합니다. 새 출력의 부모 폴더만 준비하고 gape-observation-01은 만들지 않습니다. 경로를 추측해 소스 범위를 넓히지 않습니다.
gape_exe="/absolute/path/packr-gape"
gape_manifest="/absolute/path/approved-manifest.json"
gape_output="$HOME/gape-observation-01"
test -f "$gape_exe" && test -f "$gape_manifest" || exit 1
test ! -e "$gape_output" || exit 1
"$gape_exe" snapshot "$gape_manifest" "$gape_output" || exit 1
"$gape_exe" validate-snapshot "$gape_output/gape-architecture-snapshot.json" || exit 1
ls -la "$gape_output"$gapeExe = 'C:\absolute\path\packr-gape.exe'
$gapeManifest = 'C:\absolute\path\approved-manifest.json'
$gapeOutput = Join-Path $env:USERPROFILE 'gape-observation-01'
if (!(Test-Path -LiteralPath $gapeExe -PathType Leaf) -or !(Test-Path -LiteralPath $gapeManifest -PathType Leaf)) { throw 'Executable or approved manifest missing' }
if (Test-Path -LiteralPath $gapeOutput) { throw 'Choose a fresh output path' }
& $gapeExe snapshot $gapeManifest $gapeOutput
if ($LASTEXITCODE -ne 0) { throw 'Snapshot failed' }
& $gapeExe validate-snapshot (Join-Path $gapeOutput 'gape-architecture-snapshot.json')
if ($LASTEXITCODE -ne 0) { throw 'Snapshot validation failed' }
Get-ChildItem -LiteralPath $gapeOutput무엇을 읽나: snapshot 명령의 JSON에는 snapshot ID와 노드·관계·finding 수, execution_authority: NONE이 표시됩니다. finding 수가 0일 것이라고 가정하지 않습니다. 검사 결과와 실제 생성 파일을 보존하고, 동봉된 뷰어가 있으면 그 파일을 엽니다. 뷰어가 없다면 snapshot JSON을 편집기에서 읽습니다. HTML 파일 이름을 임의로 추측하지 않습니다.
짧은 과제: 노드 하나의 이름·소스 리비전·연결된 관계·관찰 한계를 기록합니다. 이전 snapshot과 비교하려면 두 원본을 보존하고 제공된 compare before.json after.json 명령의 지원 여부를 릴리스에서 확인합니다. 관찰 밖의 동작은 추정하지 않습니다. 내부 엔지니어링 snapshot은 외부 공유하지 않고 승인된 PUBLIC_SAFE 투영을 사용합니다.
막히면: 실행 파일 없음은 설치 준비, 소스 경로/리비전 없음은 승인 입력 준비, snapshot 검사 실패는 관찰 검사 단계로 기록합니다. 아래 GAPE-1/2로 이동하며 임의 manifest 작성으로 관찰 범위를 확대하지 않습니다.
사용할 때
연동 담당자가 제안한 작업이 어느 구성요소와 인터페이스에 의존하는지 파악할 때 사용합니다. 해당 릴리스가 GAPE 도구와 승인된 입력 매니페스트를 제공하는지 확인하십시오. 일반 소스 폴더·스크린샷·아키텍처 인포그래픽은 매니페스트가 아닙니다.
관찰 준비
- 승인된 소스 버전, 관찰할 폴더, 제외 대상, 예상 규칙과 공유 범위를 기록합니다. GAPE 결과는 선택한 저장 버전에 대한 관찰입니다. 저장하지 않은 변경이나 실제 실행 중의 동작은 결과에 포함되지 않을 수 있습니다.
- 구성요소 목록에
packr-gape와 승인된 매니페스트가 있다면 새 출력 폴더에서packr-gape snapshot manifest.json new-output-folder를 실행합니다. 둘 중 하나가 없다면 지원되는 관찰 절차를 문의하십시오. - 해당 명령이 제공된 경우
packr-gape validate-snapshot gape-architecture-snapshot.json으로 생성 결과를 확인합니다. 이는 snapshot의 구조·출처 검사이지 실제 런타임 동작 검증이 아닙니다. - 승인된 오프라인 뷰어에서 노드·관계 하나를 선택하고 소스 리비전과 관찰 한계를 적습니다. 별도 Contract 또는 소유자 규칙과 대조하십시오.
UNRESOLVED·STALE은 그대로 이슈로 남기며 뷰어를 고쳐 일치처럼 표시하지 않습니다. - 허용된 곳에는 PUBLIC_SAFE 투영만 공유합니다. 엔지니어링 입력·내부 경로·소스 위치·상세 판정은 승인된 엔지니어링 환경에 보관합니다.
실제 릴리스가 GAPE를 제공할 때의 명령 예시
아래 명령은 설치 목록에 packr-gape와 조회 권한이 있는 소스용 승인 매니페스트가 모두 있을 때만 사용하십시오. 출력 폴더는 새로 만들어야 합니다. validate-snapshot은 snapshot 검사이며 실행 중인 어플라이언스 검사가 아닙니다.
packr-gape snapshot approved-manifest.json new-observation-folder
packr-gape validate-snapshot new-observation-folder/gape-architecture-snapshot.json실제 릴리스가 생성한 파일명이 다르면 그 이름을 사용합니다. 매니페스트 지문·소스 리비전·snapshot ID·검사 결과와 execution_authority: NONE을 기록하십시오. 실행 파일이나 승인 매니페스트가 없으면 이 경로를 중지하고 이번 릴리스에서 미제공으로 기록합니다.
예시: 도표에 어댑터 연결이 보임
운영자가 GAPE snapshot에서 PackrGUI와 연동 어댑터 사이의 관계를 봅니다. 이 관계는 STATIC_SOURCE입니다. 실제 고객 런타임은 다른 기능 구성으로 동작할 수 있고 동적 호출은 저장된 소스 관찰 범위 밖일 수 있습니다. snapshot에 표시된 정확한 소스 버전을 기록하고 담당자에게 제공된 Contract와 연결 증거를 확인하십시오. 배포 기록에 “연결됨”이나 “승인됨”이라고 쓰지 않습니다.
예시: 관찰과 예상 규칙이 다름
snapshot에 인터페이스 연관은 있지만 예상 소유자 규칙이 없거나 다른 리비전의 규칙입니다. GAPE는 UNRESOLVED 또는 STALE을 표시합니다. 매니페스트 신원·snapshot 지문·판정·정확한 리비전을 보존하십시오. 담당자가 Contract와 소스를 별도로 대조해야 하며 그림을 새로 그리는 일은 복구가 아닙니다.
완료 증거
매니페스트, snapshot 검증 결과, 선택한 투영, 리비전, 공개 등급, 관찰 한계와 미해결 판정이 기록되면 관찰이 끝납니다. 연동 등록과 Work는 별도 절차입니다. Integration Helper 또는 Contract & Document 안내로 이어가십시오.
단계별 실제 사용 용례
예를 들어 새 연동 요청 전에 담당자가 데이터가 어느 구성요소를 거치는지 검토합니다. 승인된 매니페스트의 저장 리비전을 고정하고 노드 하나와 그 관계를 추적합니다. 관찰 출처와 확인되지 않은 동적 경로를 함께 적고, 다른 리비전의 문서와 비교할 때는 두 리비전을 모두 표시합니다. 운영 장애 원인을 이 그림만으로 확정하지 않습니다.
증상별 확인과 복귀 확인
| 증상 또는 상황 | 분리해서 확인할 사실 | 조치와 다시 확인할 결과 |
|---|---|---|
| 소스가 바뀌었는데 이전 snapshot을 보고 있음 | snapshot 생성 시점·소스 리비전·매니페스트 지문 | 승인된 새 입력으로 새 출력 위치에 관찰을 만들고 이전 snapshot과 구분합니다. |
| 노드가 보이지 않음 | 매니페스트 범위·제외 규칙·지원 언어와 선택한 필터 | 검색 범위를 확인하고 관찰 범위 밖 또는 미확인으로 기록합니다. 기능 부재로 단정하지 않습니다. |
| 공유 자료에 내부 경로가 포함됨 | 선택한 투영의 공개 등급과 승인된 내보내기 | 공유를 중단하고 PUBLIC_SAFE 자료가 제공되는지 확인합니다. 원본 상세 내보내기를 전달하지 않습니다. |
다음 담당자에게 넘길 최소 기록
인계 항목: 소스 리비전, 매니페스트 지문, snapshot 지문, 관찰 범위, 공개 등급, 선택한 노드·관계, 미해결 항목과 다음 확인 담당자. snapshot 검증 결과와 실제 런타임 증거는 별도로 기록합니다.
도구별 문제 해결 사례 읽기
다음은 지원되는 입력·명령·권한 경계를 바탕으로 구성한 교육용 사례입니다. 제품의 실제 상태·사유와 함께 읽고, 자신의 실행 기록 없이 예시의 결과를 성공 이력으로 사용하지 않습니다. 온라인과 오프라인 환경 모두에 적용되는 확인 항목과 선택 의존성 경로에만 해당하는 항목을 구별합니다.
상세 예시 GAPE-1: 코드는 변경됐지만 예전 snapshot을 검토함
상황: 담당자가 현재 설계와 다르다고 보고한 그림은 이전 저장 리비전의 snapshot입니다. 현재 소스, 승인 매니페스트와 관찰 결과의 리비전을 먼저 구별합니다.
관찰을 이렇게 나눠 읽습니다.
- 그림: 특정 snapshot ID·소스 리비전을 가집니다.
- 현재 소스: 저장되지 않은 변경은 관찰에 포함되지 않을 수 있습니다.
- 검증: snapshot 구조 검사는 런타임 검증이 아닙니다.
확인·조치 순서:
- 매니페스트 지문·snapshot 생성 시점·정확한 저장 리비전을 대조합니다.
- 새 관찰이 필요하면 승인된 입력과 제공된 명령으로 새 출력 폴더를 사용합니다.
- 이전·새 결과를 함께 보존하고 변경된 관계와 관찰 한계를 표시합니다.
다음 단계로 돌아갈 조건: 현재 검토 대상 리비전과 검증된 snapshot이 맞으면 그 범위의 관찰 검토를 계속합니다.
해결되지 않았을 때: 매니페스트나 리비전이 미확인이면 그림을 고쳐 일치시키지 않고 해당 관찰을 미확인으로 남깁니다.
상세 예시 GAPE-2: 필터 또는 관찰 범위 때문에 노드가 보이지 않음
상황: 검색에서 구성요소가 나오지 않아 기능이 없다고 생각합니다. 하지만 선택한 필터·매니페스트 제외 규칙·지원 언어에 따라 표시와 관찰 범위가 달라질 수 있습니다.
관찰을 이렇게 나눠 읽습니다.
- 검색 결과 없음: 화면의 선택 범위에 대한 결과입니다.
- 매니페스트: 관찰 폴더·제외 규칙을 정합니다.
- 구현 부재: 이 화면만으로 확정할 수 없습니다.
확인·조치 순서:
- 검색어·필터를 확인하고 원래 관찰의 범위·리비전·제외 목록을 읽습니다.
- 다른 범위가 필요하면 승인된 입력을 가진 담당자에게 요청합니다. 내부 자료를 공개 뷰에 추가하지 않습니다.
- 관찰 밖·표시 필터·실제 미확인을 구별해 기록하고 필요한 소스 근거를 담당자에게 인계합니다.
다음 단계로 돌아갈 조건: 해당 리비전과 범위의 관계를 확인한 경우에만 그 관찰을 인용합니다.
해결되지 않았을 때: 소스 근거가 없으면 미구현·기능 없음으로 단정하지 않습니다.
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 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
- Part.1 · Install and prepare
- Part.2 · Observe structure with GAPE
- Part.3A · Plan with Integration Helper
- Part.4 · Write the source Document and bind the published target Contract
- Part.3B · Check the complete request and identify implementation needs
- Part.5 if needed · SDK candidate, implementation review and separate registration
- Part.6 if needed · Builder Pack candidate and its approval path
- Part.7 · Permitted GUI or headless operation
- Part.8 · Results, troubleshooting and human review
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.jsonSource-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.jsonThe 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.jsonA 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.jsonIntentional 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 reportsThree 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.
가이드와 Part.1–8 연결
가이드에서 목적을 고른 뒤 해당 Part에서 정확한 도구 단계를 확인합니다. 두 문서는 같은 순서·용어·자료 역할을 사용합니다.
목적별 가이드
- PoC 공통 가이드
질문을 정하고 범위에 맞는 관찰을 모아 결과를 검토합니다. 보존 기록 독해에는 신규 설치가 필요하지 않습니다.
- Google 심사자 가이드
정확한 심사 전달물과 기준 증거를 연결합니다. Cloud 접근·문서 범위·실제 Google 승인은 각각 구분합니다.
- 온프레미스 가이드
정확한 OS·패키지·네트워크 선택·도구 체인을 준비합니다. 로컬 SDK 준비 요건이 제공된 뒤에만 해당 단축 경로를 사용합니다.
- Custom Execution 가이드
지원 작업을 선택합니다. 소스 문서 준비·전체 SDK 후보·실제 Work 및 보고서 확인을 서로 다른 경로로 구분합니다.
- 가이드 링크는 네트워크가 필요한 공개 웹사이트를 엽니다. 이 오프라인 매뉴얼과 로컬 예제는 네트워크 없이 읽을 수 있습니다.
권장 연동 순서와 단축 경로
- Part.1 · 설치·준비
- Part.2 · GAPE 구조 관찰
- Part.3A · Integration Helper 계획
- Part.4 · 소스 Document 작성·게시된 대상 Contract 연결
- Part.3B · 전체 요청 확인·구현 필요 여부 확인
- 필요 시 Part.5 · SDK 후보·구현 검토·별도 등록
- 필요 시 Part.6 · Builder Pack 후보·승인 경로
- Part.7 · 허용된 GUI·헤드리스 사용
- Part.8 · 결과·문제 해결·사람 검토
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.jsonstatus.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.jsonfixture 응답 값 두 개만 바꾼 두 번째 전체 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만으로는 충분하지 않습니다. |
