Add-ons
Layer 6. Services. Services
An add-on is a versioned variable bundle an app publishes so
an operator can install a known-good configuration by name instead of
setting individual --vars. An add-on is installed by naming it:
shc install nextcloud/talk # the canonical form, no other flagshc install nextcloud/talk@latest # `@<version>` rides the last segmentshc install <app>/<addon> # an app-level add-on, same spellingshc install nextcloud/talk --into nc # only when the host deployment is not `nextcloud`The vApp segment is never typed. nextcloud/talk resolves to (app
nextcloud, vApp plugin, add-on talk) because talk.addon.yaml
itself declares vapp: plugin. The catalogue already holds that fact, so
asking an operator to restate it (and to know the middle segment of a
path they never chose) bought nothing. There is no --addon flag: the
app and the add-on are one token, and a malformed one refuses with
X400063ADNTOK rather than being reinterpreted.
The default case needs nothing on top of the token. A vApp add-on is
addressed <host_deployment>/<instance>, and the install token already
is that address: with no --into the deployment defaults to the token,
so nextcloud/talk lands as the talk instance under the nextcloud
deployment. The three shapes:
| Command | Host deployment | Instance |
|---|---|---|
shc install nextcloud/talk | nextcloud | talk |
shc install nextcloud/talk --into nc | nc | talk |
shc install nextcloud/talk --into nc --instance talk-eu | nc | talk-eu |
--into <deployment> is the one form for an add-on instance. The
instance is still the add-on. Reach for it when the parent deployment is
not named after the app, which is the common real case: the bitspur
estate’s Nextcloud deployment is nc, so there it is
shc install nextcloud/talk --into nc. An explicit --instance wins,
and is how two instances of one add-on live under one parent. -s names
a deployment being created, which an instance never is: a slash-free
-s on a vApp add-on refuses with X400060ADNHST, which prints the
--into line to type.
One file is one add-on. The file’s stem is the add-on’s identity
(the literal token an operator types after the app’s /), and the
directory it sits in is its parent app. There is no catalogue map
file to keep sorted, no name declared twice, and adding an add-on is
adding a file.
An add-on is typed, and the type decides what it installs into. An
add-on that declares vapp: <name> belongs to that vApp
and installs as an instance inside a running host deployment; an add-on with
no vapp: key configures the app itself and installs as a plain
deployment of the parent app. Crossing the two is a type error (a
vApp add-on’s variables are vvars, meaningless to the parent app), and
it refuses with X400055ADNTYP. The token grammar means an install
command can no longer express the crossing at all: the resolver reads
the target off the file rather than off anything the operator typed. What
can still cross is an authored plug pin
(addon: inside a vapp: block) and the explicit three-segment form
below, which is why the refusal stays. The tree ships 119 add-ons
across four apps
today: apps/flagship/frappe (21), apps/flagship/nextcloud (43) and
apps/integrated/wordpress (54), all against a plugin vApp, plus
apps/integrated/multiplatform (1), which carries no vapp: key and so
configures the app. This paragraph used to say no app shipped an
app-level bundle at all; multiplatform landed one and the sentence went
stale without anything noticing, which is the same class of rot the
freshness guard exists for. Both shapes are carried into the marketplace
by the catalog seeder, and
tests/unit/catalog/marketplace_addon_seed_test.go holds the app-level
branch open specifically because ONE app exercises it; losing it
would cost a single row out of 119 and clear every floor.
Source: modules/app/addon.go
(schema + resolution) and
modules/app/addon_loader.go
(the loader bridge that walks the addons/ directory). The read-only CLI
over the catalogue is shc addon.
| File | Scope |
|---|---|
apps/<bucket>/<app>/addons/<name>.addon.yaml, with vapp: <v> | one add-on for that vApp, installed as shc install <app>/<name>, which lands as instance <name> inside the host deployment |
apps/<bucket>/<app>/addons/<name>.addon.yaml, without vapp: | one add-on for the app itself, installed as shc install <app>/<name>, the same spelling, which lands as a plain deployment of <app> |
apps/<bucket>/<app>/addons/README.md | catalogue-wide commentary; per-add-on commentary lives in each .addon.yaml |
The vapp: key is what replaced the two-file split. The old shape
was two different files (a bare presets.yaml for the app and a
<vapp>.vpresets.yaml per vApp), and which file an entry lived in was
what typed it. Now every add-on lives in the same directory under the
same suffix and declares its own target: present means “this configures
that vApp”, absent means “this configures the app”. One file shape, one
directory, and the type is a key you can read rather than a filename you
have to notice.
The directory is flat and alphabetical by construction: the listing
is the ordering, because the filenames are the names. An add-on whose
file exists and does not parse is refused loudly with
X400054ADNMAL, naming the file: a malformed catalogue entry is never
skipped, because a silently skipped entry is a catalogue reporting a
smaller truth than the one on disk.
Format
Section titled “Format”# apps/<bucket>/<app>/addons/<name>.addon.yaml: every key; most are optionalvapp: plugin # omit to configure the APP itselftitle: Talk # store heading; defaults to the filename stemdescription: "encrypted chat, audio, and video calls"homepage: https://apps.nextcloud.com/apps/spreedicon: addons/talk.svg # PACKAGE-relative, like app.yaml's iconcategory: communicationtags: [chat, video, voip]hidden: falsedefault: latestversions: latest: appId: spreed commit: "" # optional; a git add-on may pin an exact objectaliases: stable: latestvars: someConstant: value| Key | Meaning |
|---|---|
vapp | optional: the vApp this add-on configures. Absent = the add-on configures the app itself, and it is then only nameable on a bare shc install <app>. |
title | optional store heading; defaults to the filename stem. The stem stays the identity either way: title: never changes what an operator types, and it does not resolve as an install token. It is title and not name because the add-on’s NAME is already the filename; a second field spelling the same fact is a second source of truth. |
description | the tagline, never prefixed with the title: the listing renders heading and tagline separately, so a prefixed description prints the name twice. required. What the catalogue gate checks for and what the storefront renders. |
icon | optional, app-relative, the same convention app.yaml’s icon: uses. Omitted, the loader looks for a sibling sharing the stem: addons/<name>.{svg,png,webp,jpg}. A remote URL (http://, https://, //) is refused with X400054ADNMAL: the storefront’s provenance claim is that the bytes it renders are bytes this app ships, and a URL makes that unprovable while putting a third-party fetch on every listing render. |
homepage | optional upstream URL. |
category / tags | optional; carried into the synced catalogue rows shc catalog search reads. |
hidden | optional tri-state: unset, true, false. |
commit | optional, git add-ons only: the exact 40-hex object the checkout must land on. branch still does the clone; this detaches onto the pin afterwards. See below. |
vars | base variables applied for every version (per-add-on constants). |
versions | per-version variable overlays, keyed by version string. |
default | the version picked when the operator names no @<version>. |
aliases | alternate names for version keys (e.g. stable: latest). |
The old meta: nesting is gone: description, icon, homepage,
category, tags and hidden are top-level keys of the add-on
document. A file is one add-on, so there was nothing left for the
sub-map to disambiguate.
The loader tolerates a versionless add-on (just vars, no versions
block; then requesting an explicit @<version> is an error), but the
shipped catalogues do not use that shape: see the authoring rules below.
Authoring rules
Section titled “Authoring rules”The mechanism above is deliberately small: a named var bundle with a version map. Everything that makes a catalogue good is convention, and the convention is a contract (catalog.md §35.6). Two of its rules have already failed silently in production, which is why they are enforced rather than advised:
- Every add-on var name must match a vvar the vApp declares
(or, for an add-on with no
vapp:, a var the app declares). Add-on vars merge into the vars map BY NAME and an undeclared key is silently dropped: the install proceeds with the file default and the add-on has no effect. The nextcloud plugin catalogue shipped months of inert entries this way (app_idvs the declaredappId: every install got thecalendarfallback). Enforced:tests/unit/catalog/addon_var_parity_test.gofails the tree on any undeclared key. - Per-item constants in
vars, per-version deltas in theversionsoverlay. The overlay carries only what the version choice changes. - Version keys mirror upstream’s identifiers when upstream is
selectable (frappe’s git tags), a single
latestkey when it is not (nextcloud:occ app:installtakes no version, so a per-rung map would be identical vars pretending to pin something). - Name a
defaultand fill the display keys;descriptionis required. They are what the catalogue renders. Enforced: the same unit gate requires a non-emptyversionsmap, a resolvabledefault, and a non-emptydescriptionon every shipped add-on. - Pinned refs must keep existing upstream: a deleted tag or a
store release that no longer admits your shipped major is
invisible to every offline check. Enforced, but by the
network-dependent freshness guard (
make catalog/freshness), not by the unit gate: see Keeping a catalogue fresh.
Screenshots
Section titled “Screenshots”An add-on is a thing an operator chooses by name, and a name plus a sentence is a poor basis for choosing, so an add-on can have its own storefront screenshots showing what installing it actually gets you.
They are declared on the owning app’s app.yaml, in its gallery:
list, with an addon: field naming the subject:
gallery:- path: gallery/addon-deck.webp addon: plugin/deck # <vapp>/<name>; a bare <name> for an app add-on source: captured captured_from: "1.18.3" # the ADD-ON's subject version, not the app's width: 1200 height: 358 caption: A Deck board after installing this add-onThe gallery addon: token is not the install token and did not change
with the grammar: it is a within-app selector, so it stays
<vapp>/<name> (bare <name> for an app-level add-on) and picks the
subject out of one app’s addons/ directory. The install token names
the app first (nextcloud/deck); this one is already inside it.
Why not a gallery: key on the add-on itself? Because it does not ship.
ce’s v-document lint (modules/app/vdocument_lint.go) closes the add-on
document to a fixed key set (vapp, title, description, icon,
homepage, category, tags, hidden, default, versions,
aliases, vars) and refuses anything else with X400341VDCUNK, on
the rule that a key no loader reads is “parsed and DROPPED: the file on
disk looks exactly like one whose request was honoured”.
tests/unit/catalog/vdocument_lint_test.go enforces that over this tree.
The refusal is correct; teaching ce the key is the follow-up if the
declaration should ever move. In the meantime the app-level home is a
better fit anyway: the bytes already live in the app’s gallery/
directory and the byte budget is naturally per app.
captured_from names the add-on’s own subject version, not the app’s:
what the frame depicts is the plugin’s UI, so comparing it against the app’s
version: would compare two unrelated numbers. Where a catalogue has no
version knob at all (nextcloud’s, whose default is latest because
occ app:install takes no version), the freshness guard reports UNVERIFIED,
which is acknowledged with its reason in apps/GALLERY_UNVERIFIABLE rather
than passed over. See app-definition.md → Gallery
for the full schema.
Resolution
Section titled “Resolution”What <app>/<X> names
Section titled “What <app>/<X> names”<app>/<X> names one of three things, and which one cannot be
decided from the token’s punctuation, so the app is asked:
| Reading | Example | How it is recognised |
|---|---|---|
| an add-on | nextcloud/talk | the app publishes addons/talk.addon.yaml |
| a vApp instance | nextcloud/plugin | the app ships plugin.vapp.yaml; addressed -s <host_stack>/<instance> |
a fused source <repo>/<app> | myrepo/whoami | only when --stack is slash-free: no vApp instance can wear a slash-free deployment |
The add-on reading is tried first and wins when it matches, because it is
the only one of the three backed by a file on disk rather than
inferred from the shape of the token. A token the app does not
publish as an add-on falls through to the older grammar untouched, so
<repo>/<app> and its own ambiguity refusal (X400075SRCAMB) are
unchanged.
An app a registered repo supplies is asked one step later. That
first reading looks only at the apps on the node’s own app roots: no
token’s reading may depend on what a repo holds. For an app a repo
supplies, <app>/<name> therefore takes the vApp reading, and the add-on
is read once the host deployment is known to exist, from that
deployment’s own app:
shc install nextcloud/calendar --into cloud # the calendar add-on, as the vApp its file names--into with no --instance names the instance after the token’s last
name, the add-on or the vApp. A name the app ships as a vApp stays a
vApp, and the three-segment form is checked against the add-on’s vapp:
here too.
--into <deployment> names the deployment for both kinds of add-on.
An add-on typed against a vApp is installed into that deployment. An
add-on typed against the app itself is a deployment of its own, so
--into names the deployment it installs as, the same as --stack:
shc install <app>/<addon> --into shop # the deployment shop, with that app-level add-onIt has no instance, so --instance there is refused X400058ADNINS,
which prints the line to type.
A name that is BOTH a vApp and an add-on is refused, never guessed.
A vApp instance and an add-on are different objects with different
lifetimes, so a silent pick installs something nobody asked for. The
refusal is X400056ADNAMB and it names both candidates plus the escape
hatch: the three-segment <app>/<vapp>/<addon> form says exactly which,
and is itself checked against the add-on’s declared vapp:
(X400057ADNVAP): a token that contradicts the file is a disagreement,
not a preference. There are zero such collisions in this tree today
(the only vApp name any add-on-publishing app ships is plugin), and
the catalogue gate refuses one at authoring time, so the three-segment
form is documented as an escape hatch for third-party apps and is
deliberately not used in any example above.
How the add-on itself resolves
Section titled “How the add-on itself resolves”<app>/<name>[@<version>] resolves in this order:
- Type check: the add-on’s
vapp:key (present or absent) decides the install target rather than being checked against one an operator typed:vapp: pluginmakes the install a vApp instance under a host deployment, an absentvapp:makes it a plain deployment of the app. A crossed pairing that reaches the resolver from somewhere the token grammar does not own (an authored plug pin, or an explicit<app>/<vapp>/<addon>naming the wrong middle segment) still refuses withX400055ADNTYP/X400057ADNVAPbefore anything else happens. - Version pick: the explicit
@<version>if given, else the add-on’sdefault(an add-on withversionsbut nodefaultrequires an explicit version).aliasesare dereferenced, and the special versionlatestpicks the highest semver-ordered key. - Merge:
vars(base) ⊕versions[<resolved>]⊕ any operator--varoverrides, later layers winning. - Persist: the resolved version key is recorded in the deployment state so re-renders and upgrades stay symmetric.
The coded failures, all of which name what they could not find:
| Code | Meaning |
|---|---|
X404019ADNNFD | no add-on by that name in the app; the message lists what the app does publish |
X404021ADNEMP | the app publishes no add-ons at all |
X404022ADNPIN | a plug’s vapp: block pins a version the add-on cannot serve; a pin is never silently moved |
X400052ADNVRN | version error (unknown or ambiguous), with the available version list in the message |
X400054ADNMAL | the .addon.yaml exists and does not parse: refused loudly, never a silent skip |
X400055ADNTYP | the add-on was resolved against the wrong target (app add-on on a vApp install, or the reverse) |
X400056ADNAMB | <app>/<name> names both a vApp and an add-on: refused, naming both candidates and the three-segment form |
X400057ADNVAP | <app>/<vapp>/<addon> named a vApp the add-on does not declare; the file owns that fact |
X400058ADNINS | --into <deployment> --instance <name> on an add-on typed against the app itself: it is a deployment of its own and has no instance. The message names the line to type |
X400063ADNTOK | the add-on target token is not <app>/<addon>[@<version>]: the app and the add-on are one token |
Inspecting add-ons
Section titled “Inspecting add-ons”shc addon ls <app> # everything the app shipsshc addon show <app>/<addon>[@<version>] [--vapp <v>] # resolved var mapshc addon versions <app>/<addon> [--vapp <v>] # version keysshc addon show and shc addon versions take the same one token
shc install takes, so an operator never learns two spellings for one
address. Two positional arguments are refused with a message naming the
one-token form. On versions an @<version> in the token is dropped
rather than refused: the verb lists them, so a version there is noise.
An add-on’s own file names its vApp, so --vapp is optional. Given, it
narrows the search to that vApp’s add-ons.
Those three read the on-disk apps tree: they answer questions about a app you have. To search the SYNCED catalogue, including add-ons published by a repo this node has never installed from:
shc catalog search <query> # the synced catalogueshc catalog ls # every app and add-on a registered repo suppliesFor an app no root on this node holds they answer X404012APPDIR and say
so. Name an unpacked app with --app-dir <dir>, or read the add-ons a
repo supplies from shc catalog ls.
Re-pinning an installed add-on
Section titled “Re-pinning an installed add-on”There is no flag, and the rule is the RECORDED STATE, not the token’s punctuation: if a deployment was installed by naming an add-on, the version an operator names on update is the add-on’s version. That covers both shapes with one sentence.
On a vApp instance it could not mean anything else: an instance has no
app version of its own, it borrows the host deployment’s, so routing
@<version> to the app version would silently re-render the parent at a
version nobody named. An app-level add-on is a plain deployment and
does have an app version, which is why the rule has to be stated rather
than inferred from the slash.
The cost, stated rather than hidden: an add-on-installed deployment’s app version is no longer separately pinnable on update: it follows the catalogue. That is what an operator who pinned the add-on is asking for. If the pair ever has to move together, re-install and name both halves.
See the shc addon CLI reference for
flags.
And on the marketplace: the catalog seeder
(frappe/apps/marketplace/scripts/import_catalog.py) carries every
add-on file into the bench as a store row, and the storefront renders
them in an Add-ons section on the app’s detail page (description,
category, tags, the default version key, and the shc install <app>/<name> line), one shape for both types now, because the vApp
segment left the command. The seeder still stores vapp on every row: it
is what makes an add-on listing addressable as a distinct object
(parent_app, vapp, addon_key) and what a gallery entry’s addon:
token is matched against, but it is no longer readable off the printed
command. An app that publishes no
addons/ directory renders no section: the page is byte-identical to the
one it rendered before add-ons existed. An add-on whose unmaintained
hard guard is set is shown as such, carrying the guard’s own text and the
--var acknowledged=true its command needs: a store that offered a
command the install refuses would be worse than one that stayed quiet.
Declaring add-ons in a deployfile
Section titled “Declaring add-ons in a deployfile”A deployfile lists the vApp add-ons its deployment carries under
addons:, each as the add-on half of the install token, with an optional
version:
stack: nextcloudcatalog: nextcloudaddons: - otpmanagerenvironments: prod: {}shc deploy installs each into the deployment after it has deployed, in
file order, as shc install nextcloud/otpmanager --into nextcloud. An
add-on already there is updated, shc update nextcloud/otpmanager latest,
to the file’s version or the catalogue’s newest when the file pins none,
the same rule the deployment’s own version follows. --dry-run prints
each add-on’s step after its deployment’s. The list needs a catalog:
file, since catalog: supplies the app half of the token.
Pinning a git add-on to an exact commit
Section titled “Pinning a git add-on to an exact commit”branch: main is not a pin. It names wherever the tip happens to be on the
day something clones it, and the commit recorded beside it in a comment is
read by nothing: frappe_keycloak’s said 98482d21 while main had been
a98cca51 for two weeks, and three benches were running three different
versions of that app as a result (SHC-692).
So a git add-on may name the object itself:
versions: main: branch: main commit: 1134cc057e13afd7a4106c4f9d93d1cedf2e49beBoth keys, not one. bench get-app clones with
git clone <url> --branch <ref>, which accepts a branch or a tag and refuses
a raw commit, and several bitspur-owned repos publish no tags at all. The
branch does the clone; the commit is reached afterwards with
git fetch --depth 1 <url> <commit> and a detached checkout. That fetch
resolves an object that was never a branch tip (measured against gitlab.com),
which is what makes a merge commit’s parents pinnable.
Full 40 hex, always. An abbreviated id is ambiguous by construction and
git fetch refuses it, so a short pin fails mid-install rather than at
authoring time.
Empty means unpinned, which is every other add-on’s behaviour unchanged.
What honours it
Section titled “What honours it”| consumer | when |
|---|---|
plugin.vsocket.yaml’s install-plugin job | at install: a clone it made must land on the pin or be rolled back; an ADOPTED tree (baked, no .git) reports that it could not and carries on |
frappe-app-pin.job.yaml | on every post_install / post_update: converges an existing bench, and is the only carrier that reaches a bind-mounted one |
make catalog/addon-commit-pins | asks the remote whether the object is served at all: a git fetch --dry-run, so it writes nothing |
The pin has to be carried through the whole vApp pass-through to reach the
job: declared in plugin.vapp.yaml, defaulted in plugin.vvars.yaml, put on
the wire in plugin.vplug.yaml’s data:, and named in the vsocket schema.
Miss the data: hop and the key resolves undefined, default() catches it,
and the pin is dead code that nothing reports, which is exactly what happened
to replace before it was measured.
Keeping a catalogue fresh
Section titled “Keeping a catalogue fresh”An add-on catalogue is a curated list with no live upstream wiring. Whatever upstream said when you authored it (that a tag exists, that an app-store release admits your server major, that a plugin slug is still served) is frozen into the file the moment you save it. The file then stays internally consistent while the world moves, so no offline check can see it rot. Two ways it does:
- a deleted or renamed upstream ref turns into a broken install, discovered by whoever installs it;
- an app that loses its release for the major you ship turns into a silent disable at upgrade: the app stops loading, its data goes dormant, and nothing reports it.
make catalog/freshness re-asks the upstreams
(cmd/verify-addon-freshness).
It resolves every git ref with git ls-remote, reads bench’s own
[tool.bench.frappe-dependencies] gate at each ref, asks the Nextcloud app
store per ladder rung, and asks api.wordpress.org per slug, then compares each
answer with the upstream version apps/<bucket>/<app>/vars.yaml currently
pins. It also crosses the two axes an add-on install is chosen on (the app
version × the add-on version), because a combination can be impossible while
each half looks fine, and re-asks the (ref -> commit) revisions each add-on
records in its own comments. CI runs it on release tags and on the daily
schedule; it gates nothing.
What it expects from a new catalogue:
- A
defaultthat installs on the rung you ship. This is the one rule the guard treats as a hard failure rather than a warning. For frappe add-ons the test is upstream’s own:bench get-appreads[tool.bench.frappe-dependencies] frappe = "<spec>"from the app’spyproject.tomlat the ref being installed and refuses the ref when the spec admits no version of the running framework. Adefaultpointing at such a ref makes the unversionedshc install <app>/<name>an install that cannot succeed, so the guard reports it BROKEN. The listed v-next refs are a different matter and stay a WARNING: a catalogue that carried only the shipped rung’s refs could not express the next one, andshc install frappe/[email protected]has to keep resolving. Pointdefaultat the newest ref the shipped rung admits; keep the rest listed. - A readable shipped rung. The app’s
imagespin invars.yamlmust carry a version tag the guard can read a major out of. A floating tag (:latest) is refused, because there is then no “current” to validate against. - A recognised add-on shape. The guard knows git refs (
url+branch), Nextcloud app ids (appId) and wordpress.org slugs (slug/source). A new shape must be taught to it in the same change that introduces it: an unknown shape is refused rather than skipped, because a skipped subject is a guard reporting green over something it never looked at. - A reason for anything unmeasurable. “Could not look” is never a pass. If
an upstream is structurally unreadable (a private repo a credential-free
clone cannot see), name it in
apps/FRESHNESS_UNVERIFIABLEwith a reason. That list is self-stale-ing: it fails if an entry turns out to be measurable after all, and if an entry matches no add-on. - A version key that names the app-version line it actually serves. The
guard crosses the two axes rather than checking each alone: a key spelled
v16.30.0declares it serves the 16 line, so the ref it points at must declare, in its own[tool.bench.frappe-dependencies]spec, that it serves 16. When it does not, the pair installs on no core at all: not on the line the key names, and not by asking for the line the ref serves, because no key names it. Both halves pass every per-axis check (the tag resolves; the constraint is real upstream text), so this is BROKEN, not the by-design warning a refused v-next pin earns. Which majors count as core lines is measured, not assumed: an independently versioned app whose keys spell its own release number ([email protected]) is exempt, and the exemption is printed. - A recorded revision that still resolves to itself. Where an add-on writes
down the commit id it verified a ref at (
v15.59.0 -> 4c3044cd…), the guard re-asksgit ls-remote. A tag that upstream deleted and re-cut still resolves, so nothing else can see it: the pin’s name now names a different tree, and every fact recorded beside it describes a revision that is gone. That is BROKEN for a release-shaped ref and a warning for a branch tip. Record the id in the same comment shape the catalogue already uses (<ref> -> <object id>) so the parse keeps finding it. - A hard guard whose named rung still works. A guard that tells an operator
to acknowledge “only when the target server is on rung 31” is a claim about a
pair, and the guard re-asks the store at that rung. The rung an operator is
pointed at going dead is BROKEN (the one install path the catalogue still
offers is then empty), and a rung whose feed could not be read is
UNVERIFIED, acknowledgeable as
rung:<app>:<major>.
If an add-on is genuinely uninstallable on the rung you ship but must stay
listed (an estate still runs it, or a restore of an older capture wants it), the
catalogue’s own answer is the hard guard: set a non-empty unmaintained var
stating the measured facts. The install then refuses before it touches upstream
unless the operator passes --var acknowledged=true. The freshness guard reports
such an add-on as correct-by-design, and reports the guard itself as stale once
upstream starts serving your rung again.