§2 Pack model

2.1 Package#

1. A Harness Pack is a directory (the pack root).
2. A pack MUST contain these three files at the pack root: surface.json, policy.json, HARNESS.md. Filenames are exact and case-sensitive.
3. A pack MAY contain additional files. Runtimes MUST NOT assign protocol semantics to files other than the three above.
4. Runtimes MUST reject a pack root lacking any of the three files.
5. Paths declared in the manifest as relative (wrap.bin beginning with ., openapi.path) MUST be resolved against the pack root.

Informative. Path containment (rejecting relative paths that resolve outside the pack root) is proposed for HCP/1.2. Runtimes SHOULD enforce it today.

2.2 Identity#

1. A pack's identity is its pack_id, given by manifest field id.
2. pack_id MUST be 1 to 128 characters, lower-case, and stable across the pack's lifetime.
3. Policy surface_id MUST equal pack_id. Runtimes MUST reject a pack where they differ.
4. If the manifest carries protocol metadata (hcp, pack_id, …), its pack_id MUST equal id.
5. One pack_id SHOULD correspond to one maintained source repository.

2.3 Commands#

1. A pack declares its commands in the manifest verbs map. Each key is a verb_key.
2. verb_key MUST be non-empty, lower-case, and MAY contain . as a family separator. It MUST NOT contain whitespace or /.
3. A pack SHOULD declare between 5 and 12 commands. A pack MAY declare fewer. A pack declaring more than 12 SHOULD be split.
4. A pack MUST NOT expose a generic pass-through command (a command whose arguments are forwarded as an arbitrary argv). Such a command is non-conforming.
5. Every verb_key MUST have a Policy entry (§4.4).

2.4 Triggers#

1. A pack MAY declare triggers in the manifest as stimulusTriggers[], each with a ref.
2. Every declared ref MUST have a Policy stimuli entry (§4.4).
3. A pack MUST NOT declare a trigger for a condition it can only observe by polling.

2.5 Planes#

1. plane is runtime (default) or control.
2. A control pack MUST use Binding mode mothership (§8.2). Runtimes MUST fail lint otherwise.
3. Capabilities requiring different Binding modes MUST be separate packs.
4. Runtimes MUST NOT activate a control pack for a Principal lacking an explicit operator or elevation grant.

2.6 Protocol affinity#

1. A pack targets a protocol version with metadata field hcp. For HCP/1.x the value MUST be 1.
2. Runtimes MUST reject a pack whose hcp value they do not support and SHOULD report the unsupported version.
3. When the manifest does not carry explicit metadata, runtimes MUST derive it from the manifest fields (id → pack_id, kind → adapter_kind, …) and validate the derived object.

2.7 Invariants#

A conforming pack satisfies all of the following.

2.8 What is not part of the pack#

Informative. Catalog metadata, runtime grants, Principal mappings, sink configuration, UI catalogs, and delivery transports are runtime concerns. A pack that embeds them is not portable and SHOULD be rejected in review even if it passes lint.