Extension packs
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.
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 checkandvulpine pack build, incrates/vulpine_cli/src/ext_pack_verbs.rs;- the tools index’s
packs[]array, incrates/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. Itsverifystep runs this validator on a built record from alocalfolder.
- the types, the validator, contract ranges and the record writer, in
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
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]
checkruns the validator on a source or a record and its folder. The report,vulpine.extension-pack-check.v1, listsrefusals({reason, subject}),held({component, reason, detail}) andnotes.buildchecks 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 stillpending:and thepacks[]entry.- The bundled catalog’s ids come from
--catalog, elseVULPINE_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.