A reviewed Recipe can have different presentation text for different model targets without copying its authority into a new file. This guide explains the Sonny 0.12.7 contracts for authors and operators who maintain such bundles. Controlled source tests cover the variant boundary; an actual installed signature check is qualified separately. No hosted-model campaign or organization approval is implied by those fixtures.
Separate four decisions
| Decision | What it establishes |
|---|---|
| Source pin | Which repository release/files to load. It does not approve their behavior. |
| Recipe signature | Whether exact signed bytes verify against a registered trusted key. |
| Model-variant selection/approval | Whether an eligible, digest-bound presentation change may be selected for a target profile. |
| Runtime admission | Whether this session may use an endpoint, credential, tool or execution boundary. |
The source guide
explains Git-tag pins. Model-variant pins
are separate; recipe pin --help describes their session/default scope. Do not
use one kind of pin as evidence for another kind of decision.
Review a signed Recipe
The release verifies an Ed25519 signature beside a Recipe as <file>.sig against
registered trusted public keys. The signature covers the exact YAML bytes.
The installed disposable-key test resolved the valid signed file, refused it
after a comment changed its bytes, and resolved it again after exact restoration.
With signature-required policy, the unsigned file was refused.
Have your authorized distribution owner supply the reviewed files, signature and
key-registration procedure. Keep private signing keys outside source bundles and
public examples. Default Linux trusted-key storage follows
$XDG_CONFIG_HOME/sonny/pack-keys; SONNY_PACK_KEYS_DIR can select another key
directory. Policy can require signed files with SONNY_REQUIRE_SIGNED_PACK.
Changing those settings is an operator trust decision, not a repair for an
unexplained verification failure.
A root-file signature alone does not establish that every referenced fragment, parent, model catalog or server definition is the intended version. Review the resolved closure and record its digests. Signing does not grant arbitrary secret execution, approve every endpoint or make prompt text an isolation policy.
Understand a model variant
A pack_variant envelope is distinct from a version-2 Recipe. Its envelope names
the logical Recipe, variant ID, base content digest, selector, overridden
components and their expected digests, plus trust information. It cannot be
selected as a root Recipe merely because its filename ends in YAML.
Variants may change admitted mutable presentation text. They do not change tool permissions, credentials, endpoint authority, schemas, sandbox policy or the model/settings against which selection was made. Mutable masks and component addresses enforce that scope in the controlled variant tests.
The target profile describes behavioral facts of the execution target. It is separate from the model connector catalog: endpoints, accounts and credentials belong to the connection boundary. Unknown facts do not satisfy a constrained selector merely because the desired model name looks similar.
Inspect before approval or publication
After installing your reviewed source, sonny recipe variants <recipe-id> lists
discovered variants. The angle-bracket ID is a replacement from your installation.
For a named target/profile bundle, use the release’s recipe resolve --explain
and JSON output to inspect candidates, refusal reasons, selection and digests.
Check recipe resolve --help for the explicit target-profile/catalog flags.
An unapproved profile, draft variant, unavailable fact, stale base/component
digest or refused signature is a meaningful boundary. A validator accepting one
envelope does not prove that the bundle can be selected against its actual base.
Refresh digests from the reviewed content; do not invent digest strings to make
a file look complete. sonny variant-schema-gen emits this release’s envelope
schema, separately from schema-gen for ordinary Recipes.
recipe variant approve changes one named envelope’s trust status. It is an
approval action for an authorized maintainer after inspection and qualification,
not a routine first-run command. Qualification-only draft/unapproved-profile
options do not establish production approval. A variant’s approval and an
Ed25519 signature remain different records.
Measure and roll back
Keep the base files, expected component digests, target-profile revision, qualification evidence and selected variant together. A changed referenced file can invalidate the recorded identity even if the root’s display name is unchanged. Repeat selection and task checks after updating any part of that closure.
Use evaluation to compare representative inputs and retain independent task evidence. Restore a previously reviewed bundle/pin to roll back, then inspect the resulting selection. A successful source test or replay is not evidence that a live model accepted an endpoint or performed a tool operation in your client.