Part.2 · GAPE observation, comparison and sharing

GAPE: inspect a revision-bound architecture observation

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 $gapeOutput

What 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

1. 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.
2. If your component list includes packr-gape and an approved manifest, run packr-gape snapshot manifest.json new-output-folder with a new output folder. Otherwise ask for the supported observation procedure.
3. Validate the generated snapshot with packr-gape validate-snapshot gape-architecture-snapshot.json when that command is supplied. Validation checks the snapshot's structure and provenance, not actual runtime behavior.
4. 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 UNRESOLVED or STALE as findings; do not promote them to consistent by editing the viewer.
5. 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.json

Use 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

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:

1. Compare manifest digest, snapshot creation time and exact stored revision.
2. For a new observation, use approved inputs/supplied commands and fresh output.
3. 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:

1. Check search/filter settings and the original observation’s scope/revision/exclusions.
2. Request an authorized observation for another scope; do not add private data to a public view.
3. 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.

Post-install tools