Protocol specification (v0.1)

Synced from chp-core/spec/chp-v0.1.md. The repository copy is authoritative.

Status: stable (v0.1, released 2026-07-06). Changes via proposals/ — see CHANGELOG.md.

Key words MUST, MUST NOT, SHOULD, MAY are to be interpreted as described in RFC 2119. See README.md for the full specification index and reading order.

CHP v0.1 defines the smallest interoperable surface for governed execution at a capability boundary. It is language-agnostic, transport-agnostic, local-first, embeddable, and useful with one host.

1. Purpose

The Capability Host Protocol exists to make execution observable, replayable, and progressively governable at the boundary where an action is invoked.

CHP v0.1 focuses on local execution evidence. A compatible host can declare capabilities, expose discovery, accept invocation envelopes, preserve correlation, emit evidence for every execution attempt, and replay evidence by correlation ID.

The launch value proposition is:

See what your agents, tools, and systems actually did.

2. Definitions

Capability: A discrete executable action with stable identity, version, supported modes, declared invariants, an invocation boundary, and evidence emission.

Capability Host: A runtime that hosts capabilities and participates in CHP. A host may be a process, service, CLI, agent runtime, MCP wrapper, API adapter, device, or business system.

Invocation Envelope: The protocol object used to request capability execution.

Evidence Event: A structured record of execution truth emitted by a host. Evidence is not a free-form log line.

Correlation Context: The causal context carried by invocations and evidence events. It links related execution attempts.

Replay Query: A query object that asks the host to return evidence for a correlation ID.

Replay Result: The ordered evidence returned for a replay query.

Invariant: A declared constraint that describes what should hold before, during, or after execution. v0.1 supports declaration and basic host-denial semantics but does not require a rich policy engine.

Assurance Metadata: Minimal metadata describing the strength and policy of evidence emitted by a host.

Canonical v0.1 protocol object names:

• CapabilityDescriptor
• HostDescriptor
• InvocationEnvelope
• InvocationResult
• ExecutionEvidence
• CorrelationContext
• ReplayQuery
• ReplayResult

3. Capability Descriptor

A capability descriptor declares what action exists and how it may be invoked.

Required fields:

• id: stable capability identity, such as tool.add or trace_execution
• version: capability version
• description: human-readable purpose
• modes: supported invocation modes, at minimum sync
• emits: evidence event types the capability may emit

Recommended fields:

• input_schema: JSON Schema for invocation payloads
• output_schema: JSON Schema for successful result data
• invariants: declared constraints
• risk: low, medium, high, or critical
• assurance: minimal assurance metadata
• owner, tags, metadata

The stable capability URI is id:version.

Version semantics (clarification, additive): version is a semver string. Two versions with the same major component are compatible — a caller written against 1.2.0 MAY be served by any 1.x.y; a major bump signals an incompatible input/output contract. Resolution of an unversioned invoke is defined by the invocation pipeline (gate 2: it resolves only when exactly one version is registered). Registry version specs (e.g. >=1.0.0) are interpreted under these semantics.

Schema: schemas/capability-descriptor.schema.json

4. Host Descriptor

A host descriptor declares the host identity, protocol version, hosted capabilities, and evidence behavior.

Required fields:

• id: stable host identity
• version: host implementation version
• protocol_version: 0.1
• kind: host kind, such as local, service, mcp-wrapper, cli, or device
• capabilities: capability descriptors
• evidence: evidence store metadata including whether the store is append-only

Schema: schemas/host-descriptor.schema.json

5. Invocation Envelope

Every invocation MUST pass through an envelope-compatible boundary.

Required fields:

• invocation_id
• capability_id
• mode
• correlation
• subject
• payload
• requested_at

If a caller supplies a correlation ID, the host MUST preserve it. If no correlation ID is supplied, the host MUST generate one and return it in the result and evidence.

Hosts SHOULD NOT copy raw invocation payloads into evidence by default. Capabilities may emit explicit redacted evidence payloads.

Schema: schemas/invocation-envelope.schema.json

6. Execution Evidence Schema

Every execution attempt MUST emit evidence.

Core event types:

• execution_started
• execution_completed
• execution_failed
• execution_denied
• execution_skipped

Capability-specific event types are allowed when they are structured and correlated. For example, the reference trace_execution capability emits execution_observed.

Required fields:

• event_id
• event_type
• invocation_id
• capability_id
• host_id
• correlation
• timestamp
• sequence
• payload
• redacted
• assurance

Evidence SHOULD be stored append-only. v0.1 does not require cryptographic tamper evidence, remote notarization, or consensus.

Schemas:

• schemas/execution-evidence.schema.json
• schemas/evidence-event.schema.json

7. Correlation Requirements

Hosts MUST:

• preserve caller-provided correlation.correlation_id
• generate a correlation ID when missing
• include correlation context in every evidence event
• return correlation context in every invocation result
• support replay by correlation ID

CorrelationContext MAY carry an optional environment (dev | test | pilot | prod) — the deployment tier the invocation ran in. When present it is recorded in evidence, so a record is provably attributed to its environment; when absent a reader defaults it to its own environment. Optional and additive: pre-existing correlations without the field remain valid.

Hosts MUST NOT silently overwrite a caller-provided correlation ID.

Schema: schemas/correlation-context.schema.json

8. Outcome Semantics

An invocation result outcome is one of:

• success: the capability handler completed and returned data
• failure: execution began but failed
• denied: the host rejected execution before the capability handler completed
• skipped: the host intentionally did not execute a registered capability, for example because it is disabled

success MUST be true only when outcome is success.

Successful invocations MUST emit execution_started and execution_completed.

Failed invocations MUST emit execution_started and execution_failed.

Denied invocations MUST emit execution_denied. Denial may occur before execution_started.

Skipped invocations MUST emit execution_skipped.

Schema: schemas/invocation-result.schema.json

9. Error And Denial Semantics

Errors describe execution failures after the boundary admits the invocation.

Denials describe boundary decisions that prevent execution, such as:

• capability not found
• unsupported mode
• capability disabled
• invariant failed
• entitlement denied, where implemented

Denial records SHOULD include:

• stable code
• human-readable message
• optional invariant_id
• retryable
• structured details

v0.1 does not require a complete entitlement system. A host may deny based on local rules or invariants.

10. Replay Semantics

Hosts MUST support replay by correlation ID.

A replay query contains:

• correlation_id
• optional limit
• optional since_sequence
• optional include_payloads

A replay result contains:

• correlation_id
• ordered events
• event_count
• replayed_at

Replay ordering is by local evidence sequence. Cross-host ordering is defined by chp-causal-order-v1 (chp-v0.2.md §7).

Schemas:

• schemas/replay-query.schema.json
• schemas/replay-result.schema.json

11. Conformance Requirements

A CHP v0.1 compatible host MUST demonstrate:

1. Capability declaration
2. Capability discovery
3. Invocation through an envelope-compatible boundary
4. Correlation propagation
5. Evidence emission on success
6. Evidence emission on failure
7. Evidence emission on denial or unsupported action
8. Replay by correlation ID
9. Representation of skipped execution, where the host supports disabled or skipped capabilities

The reference conformance runner lives in conformance/.

12. Non-Goals

CHP v0.1 does not define:

• distributed host discovery
• a required network transport
• a workflow language
• an agent framework
• a standalone entitlement / enterprise-RBAC product — CHP governs at the boundary (policy, risk tier, invariants, safety, human approval, autonomy budgets) and records each decision as first-class signed evidence; it is not a separate policy-management product
• hosted retention

Note: cryptographic proof of evidence integrity is not a non-goal — it is delivered by the v0.2 signed assurance tier (hash chain + ed25519). It was out of scope for the v0.1 baseline only.

CHP is complementary to MCP, OpenTelemetry, Temporal, Kafka, and API gateways and interoperates with them (e.g. exporting evidence as signed OpenTelemetry spans) — but it is not a re-skin of any of them: it is the one governed, signed plane, where those carry either tools without evidence, or execution telemetry without governance or integrity. CHP v0.1 stays focused on the capability execution boundary.

13. Versioning Strategy

The protocol version for this draft is 0.1.

Patch-level implementation changes may occur without changing the protocol version if schemas and conformance requirements remain compatible.

Breaking schema or semantic changes require a new protocol version. Until v1.0, breaking changes may occur, but they should be documented with migration notes and conformance updates.

Capability versions are independent of protocol versions. A capability descriptor version identifies the action contract, not the CHP protocol revision.