Docs / Reference
Lifecycle reference
Capability lifecycle states let callers distinguish declared, hosted, discoverable, invokable, governed, deprecated, and unavailable surfaces.
Plain English
Lifecycle tells callers whether the capability can be used now and how much trust to place in it.
Why it exists
Without lifecycle state, callers infer availability from transport errors and framework behavior.
Formal definition
Lifecycle is host-published metadata and runtime enforcement that describes a capability from declaration through invocation, verification, deprecation, and unavailability.
Concrete example
Ground the concept before the schema.
schedule_technician is invokable when ServiceOpsHost is available and policy checks can run.
Finds an available qualified technician and reserves a service window.
{ "id": "service-ops-host", "version": "0.1.0", "protocol_version": "0.1", "kind": "service", "capabilities": [{ "id": "schedule_technician", "version": "1.0.0", "description": "Finds an available qualified technician and reserves a service window.", "status": "experimental", "modes": ["sync"], "emits": ["execution_started", "execution_completed", "execution_denied"], "policy": { "risk_tier": "high", "auth_required": true, "approval_required": true, "allowed_actors": ["agent://planning-assistant"] }, "metadata": { "required_permissions": ["service:dispatch"], "lifecycle": "invokable" } }], "evidence": { "store": "local-append-only", "append_only": true }}Developer reference
Lifecycle state reference
CHP v0.1 standardizes descriptor maturity and invocation outcomes; hosts may expose richer lifecycle labels through registry views and metadata when they enforce them consistently.
The capability has an id, version, description, modes, and emits but may not be callable yet.
The host claims ownership of the descriptor and evidence behavior for that capability.
Callers can inspect the capability before invocation and check compatibility.
A compatible invocation may pass boundary validation and reach the handler.
The capability participates in a larger flow while preserving each host boundary.
The capability declares and actually emits structured evidence for attempts.
The capability or host has passed checks that can be inspected by relying parties.
Callers should migrate before the capability is removed or behavior changes.
The capability exists but must not execute; use denial.code such as capability_disabled when explaining why.
Relationships
Where this sits in the protocol.
Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.
Lifecycle is declared in manifests and enforced during invocation.
Registry views should expose lifecycle state.
Conformance should test unavailable and disabled paths.
Visual model
- 01Declared -> Hosted -> Discoverable -> Invokable.
- 02Restricted or blocked can apply through policy.
- 03Deprecated and unavailable must remain visible to callers.
Implementation notes
- Do not hide unavailable capabilities behind 404s when callers need migration paths.
- Separate host health from capability availability.
- Make deprecated versions visible with replacement guidance.
Common mistakes
- Using boolean available as the entire lifecycle model.
- Returning generic transport errors for lifecycle violations.
- Forgetting version compatibility when lifecycle changes.
Related concepts