Worked examples: declarations and Helper JSON

01 · One small integration, with visible checkpoints

Goal: describe a read-only status.read operation for your own service. Its input is a service name; its declared output is the service name and a Boolean health flag. Start with the document below, then use the result and error examples to learn what the Helper checks.

1. Name the target
2. Describe the source
3. Read the check result
4. Correct an input

Local example scope: source-document discovery was checked using an existing macOS Helper binary. Its exact build revision and customer distribution are unproven. Complete customer request envelopes, target binding and connected execution remain pending. The downloads alone do not reproduce the full Helper run.

02 · Contract declaration: describe intent and reference the target

The operation brief records what your service does. The CUSTOM_API document expresses that input/output shape in the supported bounded format. A product Contract is the supplier-maintained target that the Helper must match; writing a new name in JSON does not create one. The contract-reference fragment identifies the reference fields, with explicit supplier-provided placeholders. It is not a complete request and has not passed target validation.

# Status read integration brief

Illustrative requirements brief; this Markdown is not a VibePackr parser input.

- Goal: read the health status of one service.
- Caller input: `service`, a string such as `catalog`.
- Result: `service` (string) and `healthy` (boolean).
- Operation: read only; no restart or configuration changes.
- Credentials: none in this offline example; do not paste tokens into the document.
- Target contract and adapter: obtain the exact supported identifiers and revisions from the supplier.
- Completion for this example: a source document is accepted for discovery. No live service is called.

Use the fragment below to understand which target values must come from the supported product package. Keep it separate from the source document; pasting these keys into status-document.json would change the input shape.

{
  "capability_id": "SUPPLIER_PUBLISHED_CAPABILITY_ID",
  "contract_id": "SUPPLIER_PUBLISHED_CONTRACT_ID",
  "contract_revision": "SUPPLIER_PUBLISHED_CONTRACT_REVISION",
  "adapter_id": "SUPPLIER_PUBLISHED_ADAPTER_ID",
  "adapter_revision": "SUPPLIER_PUBLISHED_ADAPTER_REVISION",
  "operation_id": "status.read"
}

Completion check: every target reference is traceable to the supplied package. If the package supplies no target, record that missing standard input; do not create a custom Contract name to move forward.

03 · Document declaration: a complete source example

Describe a read-only status operation for your own service. The sample accepts a service name and describes two result fields: service and healthy. It is a fresh synthetic document; it does not announce support for a real provider. Download status-document.json and read the field table before changing it.

{
  "document_kind": "CUSTOM_API",
  "protocol_revision": "1",
  "operations": {
    "status.read": {
      "input_schema": {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          }
        },
        "required": [
          "service"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          },
          "healthy": {
            "type": "boolean"
          }
        },
        "required": [
          "service",
          "healthy"
        ]
      }
    }
  }
}

Keep the JSON structure and protocol revision. Adapt the operation name, property names and primitive types to the service you actually own. Update every required list when you rename a property. Do not add comments or explanatory description keys to this bounded document format. JSON is case-sensitive.

04 · Field reference and common editing mistakes

A schema describes possible values. It is not the actual request {"service":"demo-service"} or an observed service reply. The sample requires both output fields; a missing healthy value would not meet that declared shape.

05 · Local preparation: syntax, request envelope and result

1. Download status-document.json into a new folder. Keep the original before editing a copy.
2. If Python 3 is available, run the syntax check below from that folder. No product or network call is made. No output and exit code 0 means JSON syntax parsed successfully.
3. Inspect the fields above. A syntax check does not validate a product contract.
4. Use a complete, version-matched supplier request envelope only when available. The second command is its syntax reference; the source-document download is not that envelope.

python3 -m json.tool status-document.json > /dev/null

status-document.json is the complete source document, not the complete CLI request. R2 reads a request envelope containing request_id, correlation_id and draft; this document occupies draft.source. The local discovery check used a separate internal envelope with deliberately unbound target references and an unexecuted fixture. Do not run r2-discover directly on status-document.json or combine fragments into a claimed valid request. The full customer request package still needs an approved target binding and distribution projection.

packr-integration-helper r2-discover request.json

Command shape for a supplier-provided complete request envelope. The standalone document download is not request.json. The verified local run used an internal envelope, so this line is a command reference rather than a replayable public download workflow.

{
  "operation": "DISCOVER",
  "request_id": "example-status-discover-001",
  "status": "PASSED",
  "reason": "NONE",
  "lifecycle_stage": "DISCOVERED"
}

PASSED with lifecycle_stage DISCOVERED means the source document was accepted for discovery. It does not validate the target contract, call status.read, test reachability or grant authority. The selected result fields are verbatim values from the local run; other envelope fields are omitted. Normalizing the deliberately unbound target returned DENIED / CONTRACT_INCOMPATIBLE.

{
  "operation": "NORMALIZE",
  "request_id": "example-status-discover-001",
  "status": "DENIED",
  "reason": "CONTRACT_INCOMPATIBLE",
  "lifecycle_stage": null
}

Always inspect the JSON status and reason. R2 semantic denial can return process exit code 0. Do not build a success check that looks only at the exit code.

06 · MCP document: inspect saved observations

The MCP example is a stored initialize + tools/list transcript for the exact supported revision 2025-03-26. It uses the same status.read shapes. A bounded local discovery accepted it. This does not start an MCP server, install an agent extension or prove compatibility with an arbitrary agent. Keep the actual observed negotiated revision; changing the text cannot make a newer transcript compatible.

{
  "document_kind": "MCP_TRANSCRIPT",
  "initialize": {
    "request": {
      "jsonrpc": "2.0",
      "id": "example-init-1",
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-03-26",
        "capabilities": {},
        "clientInfo": {
          "name": "example-doc-client",
          "version": "1.0"
        }
      }
    },
    "response": {
      "jsonrpc": "2.0",
      "id": "example-init-1",
      "result": {
        "protocolVersion": "2025-03-26",
        "capabilities": {
          "tools": {}
        },
        "serverInfo": {
          "name": "example-status-service",
          "version": "1.0"
        }
      }
    }
  },
  "tools_list": {
    "request": {
      "jsonrpc": "2.0",
      "id": "example-tools-2",
      "method": "tools/list",
      "params": {}
    },
    "response": {
      "jsonrpc": "2.0",
      "id": "example-tools-2",
      "result": {
        "tools": [
          {
            "name": "status.read",
            "inputSchema": {
              "type": "object",
              "properties": {
                "service": {
                  "type": "string"
                }
              },
              "required": [
                "service"
              ]
            },
            "outputSchema": {
              "type": "object",
              "properties": {
                "service": {
                  "type": "string"
                },
                "healthy": {
                  "type": "boolean"
                }
              },
              "required": [
                "service",
                "healthy"
              ]
            }
          }
        ]
      }
    }
  }
}

Read it in order: initialize request → negotiated initialize response → tools/list request → described tool schemas. Matching request/response IDs identify each pair. This stored example omits a running transport; do not infer a server URL from the tool name.

{
  "operation": "DISCOVER",
  "request_id": "example-mcp-discover-001",
  "status": "PASSED",
  "reason": "NONE",
  "lifecycle_stage": "DISCOVERED"
}

For agent-assisted review of the same file, use the MCP observation recipe.

07 · R0 and R2 use different inputs

R0 source metadata and the R2 protocol document are different inputs. The R0 metadata fragment describes a declared endpoint and unknown observations; it does not contain the required complete R0 envelope. In the full local R0 lab, discover and normalize passed, while validate failed with ENDPOINT_UNREACHABLE because reachability was unknown. Never change unknown observation flags to true to make an example pass; obtain real bounded observations. The example.invalid endpoint is intentionally non-operational and was not contacted.

{
  "schema_version": "packr.integration-helper.v1",
  "integration_class": "HTTP_REST",
  "source_kind": "SERVICE_METADATA",
  "source_reference": "status-document.json",
  "source_revision": "example-1",
  "source_digest_sha256": "5844f2cce8405450a782f50a0b62210a417a5ef66139be138fa78761559440b5",
  "declared_protocol": "HTTPS",
  "declared_endpoint": "https://status.example.invalid/status",
  "read_only": true,
  "reachable": null,
  "security_validated": null,
  "identity_satisfied": null
}

When the supplier provides a complete R0 input, use it with the R0 command family. When a complete R2 request envelope is provided, use it with the R2 command family. Renaming one file to the other name does not convert the format.

The metadata fragment download cannot run by itself.

08 · Negative examples: diagnose, correct, recheck

{
  "operation": "DISCOVER",
  "request_id": "example-status-discover-001",
  "status": "DENIED",
  "reason": "SCHEMA_INCOMPATIBLE",
  "lifecycle_stage": null
}

{
  "operation": "DISCOVER",
  "request_id": "UNAVAILABLE",
  "status": "DENIED",
  "reason": "INVALID_REQUEST",
  "lifecycle_stage": null
}

{
  "operation": "DISCOVER",
  "request_id": "example-mcp-discover-001",
  "status": "DENIED",
  "reason": "PROTOCOL_REVISION_MISMATCH",
  "lifecycle_stage": null
}

Make one correction at a time in a copy, preserve the original result, and rerun the same supported preparation stage when its complete request package is available. Do not bypass an authority error, rename a protocol revision or assert connectivity to obtain a passing result.

09 · Mapping example: propose a correspondence

Suppose your source calls the result field service, and the approved target output calls it service_name. If both sides declare string, a rename may be represented by the supported IDENTITY transform once the exact mapping format and target are supplied. This table is a review aid, not mapping JSON.

An agent can propose this table. The Helper still checks the real request. A generated scaffold marked REQUIRES_IMPLEMENTATION is not a working adapter.

10 · A useful support record without a custom integration project

Record: product/tool version (or unknown), document kind/revision, stage reached, exact status/reason, expected result, and the one field or supplied reference in question. Use the support route with a short sanitized excerpt. Keep credentials, full logs, customer payloads and internal bundles out of the request.

Ask for a missing standard deliverable: a complete versioned example package, installation instructions, supported target reference or registration procedure. A customer-specific script should not silently become the normal onboarding path.

11 · What is complete, and what still prevents self-service

For a self-service success route, publish a versioned complete request package with supported target references, an approved customer Helper installation path and independently tested preparation results. This research closes the concrete document example gap, not those product delivery gaps.