volume purl type, making identifiers compatible with existing supply chain security tooling while precisely addressing the needs of agent component packaging. Understanding these identifiers helps you reference dependencies, target specific components, and work with trust and provenance tooling correctly.
Volume identifiers
Scopeless volumes
When a bibliotheca supports scopeless names, the identifier is simply:Scoped volumes
When a volume belongs to a publisher scope, the scope is encoded as the purl namespace with@ URL-encoded as %40:
%40 encoding is required in canonical purl strings per purl encoding rules. In user-facing contexts — manifests, search results, display — the decoded form @scope/name is used instead (e.g., @acme/research-agent-pack).
Versioned identifiers
Append a SemVer version string after@ to identify a specific release:
sha256:... digest of the release’s normalized file tree.
Component identifiers
Components exported from a volume are addressable via the purl subpath field, which takes the form<type>/<componentName>:
Component types as purl subpath values
The<type> segment in a component purl must be one of these seven values:
In authoring contexts (such as
[component-dependencies] in volume.toml), you may omit the version when the parent volume’s dependency constraint determines the resolved version. For trust, lock-like reproducibility inputs, or exact component identity, include the resolved version.
Naming rules
The same naming policy applies to scopes, volume names, and component names:- Names must consist only of lowercase ASCII letters, digits, and hyphens.
- Names must not start or end with a hyphen.
- Names must not contain consecutive hyphens.
- Scoped names must be unique within their scope.
- Component names must be unique within a volume across all component types.
purl field mapping
The table below shows how Agent Volumes identity maps onto purl fields:Logical identity vs. immutable content identity
Every published release carries two complementary identities that must both be preserved:Logical identity
pkg:volume/...@version — the package-facing release identity. Used for dependency declarations, search, display, and trust attachment subjects.Immutable content identity
sha256:<hex> — the digest of the release’s normalized file tree. Used for integrity verification, trust binding, and supply chain workflows.sha256 digest. A mismatch between the two means the release metadata is inconsistent and the release must be rejected.
Identifier resolution order
When a client needs to resolve a volume identifier to an installable release, it follows this order:1
Check the lockfile
If a lockfile is present, use the pinned versions and resolved source metadata it contains.
2
Interpret the manifest
Read dependency constraints and component references from
volume.toml.3
Query configured bibliothecas
Use package-scoped version indexes from configured registries to discover eligible version
candidates.
4
Fetch exact release metadata
Retrieve the authoritative release metadata before installation or trust evaluation. Version
index rows are resolver inputs, not final release records.
Registry-priority policy across independently configured bibliothecas is not standardized in v0.1.
Each client applies its own local policy for source selection across multiple registries.
Version lifecycle states
During ordinary dependency resolution, a client must only select versions in theavailable state. The other states affect resolution and installation as follows: