# Declare package roles and metadata

Add `meta` beside a package's `options` and `build` attributes:

<Snippet {...packageMetadata} />

Use these fields to describe the package:

* `version` identifies the package version shown by inspection commands and in
  PackageInstance records.
* `description` gives the package a short human-readable purpose.
* `owner` identifies the team responsible for it and supports governance
  scorecard rules.
* `lifecycle` classifies its state as `stateless`, `stateful`, `durable`, or
  `ephemeral`. Kix records it in the `kix.run/lifecycle` annotation. Replacing
  a package marked `stateful` triggers the deployment migration gate.
* `scope` constrains dependencies. With `scope = "namespace"`, instances in
  other namespaces cannot depend on the package. The default is `cluster`.

`version`, `description`, and `owner` describe the package. `lifecycle` and
`scope` affect evaluation and deployment behavior, so choose them carefully.

## Claim an infrastructure role

Add `meta.roles` only when the package provides one of Kix's registered
cluster infrastructure roles. This minimal provider claims the
`storageClasses` role:

<Snippet {...infrastructureRole} />

Registered roles are also dependency-resolution aliases. Kix validates role
names, prevents conflicting providers, and checks any required `out`
attributes when a consumer resolves the role.

The `storageClasses` role requires an exported `storageClassName`, so the
package root supplies it:

<Snippet {...roleOutputContract} />

Do not use roles as general package tags. Ordinary application dependencies
are resolved through instance names, aliases, or explicit `deps` wiring.

## Check the declarations

Run the normal checks after adding or changing metadata:

<Command {...check} />

Evaluation fails if a role name is unknown, two managed packages claim the
same role, or a resolved provider does not satisfy the role's output contract.