---
title: "Extension packs"
description: "extension-pack.v1 (proposed, ADR 0067; built): one installable unit over the existing carriers (tool-pack archives, inline files by sha256, hashed assets); extension-pack.toml (pending hashes, per-component from) and the extension-pack.json record share one shape; crates/extension_pack holds the one validator the CLI and the gateway call (unknown fields, closed kinds, categories, steps and capabilities, contract ranges, trust rules, inline hashes and sizes) and lists held components with their reasons; vulpine pack check and vulpine pack build run offline, the build is reproducible and prints the tools index packs[] entry."
type: "living"
source: "docs/contracts/extension-pack.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

extension-pack.v1 — one installable unit over the existing carriers: the manifest, its record and the one validator

- Status: **accepted** with ADR 0067,
  version 1.0. Built:
  - the types, the validator, contract ranges and the record writer, in `crates/extension_pack`;
  - `vulpine pack check` and `vulpine pack build`, in `crates/vulpine_cli/src/ext_pack_verbs.rs`;
  - the tools index's `packs[]` array, in `crates/vulpine_cli/src/pack.rs`;
  - the Admin protocol and the gateway's pack manager (`crates/voice_gateway/src/packs/`: the registry, receipts,
    the closed steps, the second catalog root), behind `[packs] enabled = false`. Its `verify` step runs this
    validator on a built record from a `local` folder.


## The folder

| path | what |
|---|---|
| `extension-pack.toml` | the source: the manifest below, with `pending:` hashes and, per component, an optional `from` |
| `extension-pack.json` | the record `vulpine pack build` writes: the same fields, every computable hash filled, no `from` |
| `<component id>/<path>` | each inline file a component lists (a source may read it from `<from>/<path>` instead) |
| `<archive>` | a tool-pack.v1 archive a `tool-pack` component names, when it is present |


`from` is a path relative to the pack's folder, so a first-party source under `packs/<id>/` can name a component where
it lives (`from = "../../catalog/hardpoints/mynah-nemotron"`). The build copies every inline file to
`<component id>/<path>` in its out folder (default `<dir>/dist`), so a built folder is self-contained and checks as a
record. A symlink is never read.

## The manifest

The validator holds the manifest's fields to these rules:

| rule | refuses with |
|---|---|
| a field the v1 shape does not name, at any level | `unknown_field:<name>` or `unknown_field:<component>.<name>` |
| `schema` is `vulpine.extension-pack.v1`; `id` is `^[a-z][a-z0-9-]{1,47}$` and not a built-in's (`core`) | `schema`, `id_invalid`, `id_collision:pack` |
| `version`, `min_gateway` are `x.y.z`; `title` 1-48 characters, `summary` 1-200; `license` set | `semver:<field>`, `title`, `summary`, `license` |
| `category`, `publisher` (`first_party`, `local`), `targets`, `requires` tokens, capabilities, `approval` from their closed sets | `category`, `publisher`, `targets`, `requires:<token>`, `capability_unknown`, `approval` |
| `model_load` is `ask` (installing never loads a model) | `model_load` |
| every `[contracts]` range and `[[depends]]` range is `>= M.m, < N` | `range_invalid:<name>` |
| `[steps]` names only the closed step set; no phase beyond `install`, `enable`, `remove` | `step_not_allowed:<phase>:<step>`, `unknown_field:steps.<phase>` |
| a component's kind is known and its carrier is its kind's | `kind_unknown:<id>`, `carrier:<id>` |
| a component's contract is declared in `[contracts]` with the same range (`none` only for a `model`) | `contract_not_declared:<id>`, `contract_missing:<id>` |
| a `local` pack reuses no bundled catalog id | `id_collision:<id>` |
| a `pi_extension` is never in a `local` pack, targets `pane` (with `pane_hosts` in `targets`) or `brain` | `pi_extension_in_local_pack:<id>`, `target:<id>`, `target_undeclared:<id>` |
| with `audio_in` in the pack's capabilities, every hardpoint, helper and engine is `local_only` | `audio_in_not_local_only:<id>` |
| a `voice` is `consent = "required"` and `local_only` | `voice_consent:<id>` |
| an asset has `bytes`, `license`, sources (`https://<fetch_host>/…`, `reach:fleet`, `hf-cache`) and `blake3` with a `reach:` source | `asset_bytes`, `asset_license`, `asset_sources`, `source_form`, `fetch_host_undeclared:<id>:<host>`, `asset_blake3` |
| a tool-pack component names `<…>.tar.gz` and its sha256 | `archive:<id>`, `hash_form:<id>.sha256` |
| hashes are `sha256:<64 hex>` (or `blake3:`), or `pending:ci` / `pending:owner` | `hash_form:<id>/<path>` |
| an inline file is present (when its hash is stated), matches its sha256, is under 1 MiB, is not a Mach-O; a pack's inline files under 8 MiB | `file_missing`, `file_sha256_mismatch`, `inline_file_too_large`, `inline_macho`, `inline_pack_too_large` |
| a record carries no `from` | `from_in_record:<id>` |


A component this build cannot open installs `held`, never half working: a contract outside
`THIS_BUILD_SPEAKS` (`contract_unsupported`), the kinds `avatar`, `look`
and `herdr_plugin`, and a brain-side `pi_extension`. A first-party component whose id is still in the bundled catalog
gets a note.

## `vulpine pack check` and `vulpine pack build`

```text
vulpine pack check <dir|extension-pack.toml|extension-pack.json> [--catalog <repo>] [--json]
vulpine pack build <dir> [--out <folder>] [--url-base <url>] [--catalog <repo>] [--json]
```


- `check` runs the validator on a source or a record and its folder. The report, `vulpine.extension-pack-check.v1`,
  lists `refusals` (`{reason, subject}`), `held` (`{component, reason, detail}`) and `notes`.
- `build` checks the source, fills every hash it can compute (inline files, an archive present), checks the result as
  a record against the out folder and writes it atomically. The same source gives the same bytes. Its report,
  `vulpine.extension-pack-build.v1`, carries the record's sha256, what is still `pending:` and the `packs[]` entry.
- The bundled catalog's ids come from `--catalog`, else `VULPINE_REPO`, else the checkout holding the folder; without
  one, the collision check is skipped and a note says so.
- Exit codes: 0 ok, 1 refused (or the manifest does not parse), 2 I/O, 64 usage.

## The tools index's `packs[]`

`vulpine.tools-index.v1` has an optional `packs` array; an older reader ignores it. Each entry: `id`, `version`,
`category`, `publisher` (`first_party` only; local packs are never listed), `title`, `summary`, `url` (the record's;
its files sit beside it, `<id>/<version>/extension-pack.json` under the release base), `sha256` and `size` of the
record, `min_gateway`, `license`, `capabilities`, `egress`, `approval`. An (id, version) listed twice refuses the
index. A `revoked[]` entry names a pack by its id. The index is signed as tool-pack.v1 signs it.

## Versions

A v1 reader refuses an unknown field. A pack that needs a new field raises `min_gateway`. A new category, kind or step
is a minor revision of this contract and of `THIS_BUILD_SPEAKS`.

