Esc
  • SuggestedWhat is HCP?
  • SuggestedBuild a pack
  • SuggestedPack classes
  • SuggestedSpecification
  • SuggestedCLI reference
.md

§13 Versioning

Normative versioning: the protocol version, the manifest's protocol pin, compatibility promises, and deprecation.

On this page

13.1 Protocol version#

  1. The protocol is versioned as HCP/<major>.<minor>. This document is HCP/1.1.
  2. The protocol field hcp (§2.6) carries the major only (1). A runtime MUST accept any 1.x pack.
  3. Minor versions add optional fields and tighten lints. They MUST NOT change the meaning of an existing field or remove one.
  4. A major version MAY change field meaning or remove fields. A major bump requires an accepted RFC and a migration note.
  5. A new adapter kind, Binding mode, land token, or envelope field requires an RFC. Implementations MUST NOT fork protocol names: an extension takes a new name, never a new meaning for an existing one.

13.2 Compatibility promise#

Within a major:

  1. A pack that passes lint on 1.n MUST load on any 1.m runtime with m ≥ n.
  2. A runtime MUST ignore top-level manifest fields it does not recognise (§3.1) and MUST NOT fail lint on them, unless they collide with a reserved name. The closed objects (binding §3.3, protocol metadata §3.6, and policy.json §4) keep failing on unknown fields.
  3. A runtime MUST reject a pack whose hcp major it does not implement, with error: unsupported protocol version <n>.
  4. The exec and result envelopes (§6.1 and §6.2) are frozen for the major.

13.3 Deprecation#

  1. A deprecated field MUST remain accepted for at least one minor after the deprecation is published.
  2. Runtimes SHOULD warn on deprecated fields in lint.
  3. Currently deprecated: manifest harness (inline Skill); pack-level pass_through beyond bootstrap; unnamed wrap packs (§3.5).

13.4 Pack versioning#

Informative. HCP/1.1 does not define a pack version field or a registry. Packs are identified by pack_id and distributed as directories. A version field and registry semantics are on the roadmap and will arrive by RFC.

13.5 Changes in 1.1#

Relative to HCP/1.0, RFC 0001 ("wrap hardening") made these normative:

  • Named commands are REQUIRED for wrap packs; pack-level pass-through is limited to bootstrap.
  • installer is a Binding family.
  • Land local is defined as the sandbox jail directory.
  • confirm is defined for write entries; a write MAY require it (§4.5).
  • Health commands are read and MUST NOT mint.

RFC 0008 (errata) carried the remaining text of RFC 0001 and RFC 0003 into this specification, settled the sections that disagreed, and added the lint kind write_stimulus.

13.6 Implementation versions#

Implementations (SDKs, runtimes, CLIs) version independently under their own schemes. An implementation MUST state which protocol version(s) it conforms to.