Step contract and capability handshake

:::caution Next documentation

The Describe capability handshake and contract-version enforcement described here were added after the 0.2.0 Private Preview.

:::

Nexo steps communicate with the runtime through a versioned protobuf/gRPC contract. The contract defines capability discovery and request/response processing without making a community marketplace or arbitrary plugin artifact a supported product surface.

Compatibility model

• The v1 contract is additive-only.
• A breaking wire change requires a new package path or contract generation.
• The runtime compares the advertised contract version with the supported range.
• Incompatible non-built-in steps fail closed instead of entering the processing path.

The release bundle remains the compatibility unit. Building against the contract does not guarantee that an independently packaged step is entitled, trusted, or deployable.

Capability discovery

Describe is a read-only capability handshake and can be called before Configure. The response describes:

• supported processing phases;
• contract version;
• step identity and capabilities;
• whether response processing is required.

The phase list is authoritative. A missing or invalid phase declaration must not be interpreted as a permissive default.

Configure and process lifecycle

1. Runtime starts the step process or built-in implementation.
2. Runtime calls Describe and validates the result.
3. Runtime supplies validated configuration.
4. The step processes only the phases it advertised.
5. Health, errors, and step metrics are reported through supported runtime surfaces.

Configuration acceptance is not equivalent to successful activation. Verify the active graph and exercise representative traffic.

Trust and packaging

A compatible contract is only one admission condition. The installed release can also require an entitled catalog entry, approved image or artifact digest, signed provenance, and Operator trust validation.

Use nexoctl scaffold and validate only for supported development workflows. Live publishing is not a supported 0.2.0 marketplace workflow.