Skip to main content
Use this page when you are building tooling against Agent Volumes v0.1.0-rc.1. It summarizes the implementation path and links to the canonical artifacts you need to validate behavior.
This page is an overview. The prose specification, schema artifacts, OpenAPI contract, and conformance fixtures remain canonical. The repository Implementers Guide is the source document for this orientation.

​
What you can build

Client

Validate manifests, resolve versions, download releases, verify content integrity, inspect trust metadata, and load supported component entrypoints.

Bibliotheca

Publish, index, serve, and expose release metadata, version indexes, trust metadata, advisories, and capability metadata.

Validator or exporter

Evaluate schema-backed fixtures, produce conformance reports, and export BOM/provenance mapping artifacts.

Runtime adapter

Map validated Agent Volumes components into a runtime-specific execution model without changing the portable package contract.

​
Canonical artifacts

​
Minimum viable client

A baseline client should first support the portable artifact path:
  1. Parse volume.toml with TOML v1.1.0 semantics.
  2. Validate the canonical parsed data model against volume.schema.json and prose-only semantic rules.
  3. Resolve package identities, component purls, dependency ranges, and lifecycle states.
  4. Download release bytes or source material and verify normalized-file-tree integrity.
  5. Reject digest mismatch, subject-binding mismatch, inconsistent registry state, and component permission escalation.
  6. Read trust summary/detail metadata and distinguish objective facts from local policy judgments.

​
Minimum viable bibliotheca

A baseline bibliotheca should expose the portable Registry API surface before adding local policy features:
  1. Serve GET /api/v1/capabilities.
  2. Create and finalize release upload intents for the http-put portable upload profile.
  3. Validate uploaded archives, manifest identity, byte digest, size, and normalized-file-tree integrity.
  4. Preserve version immutability and release lifecycle semantics.
  5. Serve exact release metadata, package-scoped version indexes, trust summary/detail views, and advisory discovery.
  6. Return RFC 9457 Problem Details for portable API errors.

​
Keep local policy local

Agent Volumes v0.1.0-rc.1 intentionally leaves several operational choices to implementations. Document these choices in your project rather than treating them as portable standard behavior.

​
Smoke conformance path

Run the repository artifact gates before comparing implementation behavior against the fixture corpus:
Then map implementation tests to fixture families in Conformance fixtures. Use Requirement inventory to distinguish fixture-covered behavior from prose-boundary behavior and intentionally deferred topics.

​
Suggested implementation order

  1. Manifest parsing and semantic validation.
  2. Archive profile and normalized-file-tree digest verification.
  3. Release upload intent/finalize and exact metadata fetch.
  4. Version index consumption and resolver behavior.
  5. Lifecycle/status handling for exact and ordinary resolution.
  6. Trust summary/detail read paths.
  7. Advisory read paths.
  8. Trust attachment upload.
  9. Runtime adapter loading.
  10. Local policy features such as auth UX, lockfiles, scanner ingestion, and trust-root policy.

Read the full guide

Open the repository implementers guide with the full client, bibliotheca, fixture, and ordering checklist.

Use the conformance fixtures

Start with deterministic offline fixtures before adding hosted service or trust-root policy tests.