The catalog: a design discussion
Vocabulary note: presets and vpresets have since been abolished and replaced by add-ons: one
apps/<bucket>/<app>/addons/<name>.addon.yamlper add-on, typed by the presence or absence of avapp:key. This document is left as written; the current shape isdocs/app-development/addons.md.
Status: built; this note is still its only description. Q7 is answered: outbound LDAP sits behind the paid
ssoentitlement (SSO hardening rulings, S10). Two documents existed at this path: a design-and-implementation record (Parts I–III, §1–§36) and a second concurrent session’s owner rulings (§16–§21 of a 1062-line variant on shc main). They shared §1–§15 and collided on §16–§21. This file is the single reconciled record: Parts I–III are kept as they were written, and the second session’s rulings are folded in as Part IV (§37–§44), which is also where the two genuine conflicts are settled with the owner’s word as the tiebreak.
Part I (§1–§15) is the original conversation, kept verbatim. Part II (§16–§26)
measured its open questions and records the owner’s design rulings. Part III
(§27–§36) records what building it changed, including two reversals. Part IV
(§37–§44) carries the second session’s rulings, the vocabulary ruling that
supersedes this document’s own item/tile usage, and the storage ruling that
supersedes §22–§23’s derived-catalog shape. Where later measurement or a later
ruling corrected an earlier claim, the correction lives in a corrections log
(§14, §24, §44) or in a marked SUPERSEDED note rather than a silent
rewrite. Q7 remains the only open question.
Every factual claim carries its evidence. Where a claim was made during the discussion and later measured false, the correction is recorded rather than quietly dropped; see §14, §24 and §44. Several of them were the agent’s, and the reversals are the most useful part of the record.
Baseline (Part I): shc origin/main @ d5e936e5f, ce origin/main @ 9ed5af5.
Baseline (Part II): shc origin/main @ bca4944, ce origin/main @ c99b51c.
Baseline (Part IV / reconciliation): shc origin/main @ 4ec1e105a,
ce origin/main @ 39b7f5b.
1. The core model: two layers
Section titled “1. The core model: two layers”The discussion converged on a two-layer split, proposed by the owner:
Repository: the distribution layer. Lists apps only: the
.apparchives, addressed by name and version, served from GitLab packages, a git repo, or an HTTPindex.yaml. Nothing is hidden here. It answers “what can I resolve and download?”Catalog: a higher-level abstraction over repositories. Takes each app, parses out its vapps and presets, and lists only the non-hidden ones (including apps, which can themselves be hidden from the catalog but never from the repository). It answers “what can a human choose?”
Why the split is load-bearing rather than merely tidy: hiding must never
affect resolution. A hidden vapp still has to be downloadable, or its presets
cannot install. So hidden is a catalog-layer predicate; the repository
transmits the flag as data without acting on it.
Corollary the owner drew, and it is correct: you can have many repositories
but there is only ever one catalog. The catalog is a derived view, not a
registered entity; there is no catalog table, nothing to enumerate, nothing
to add. One refinement: it is one catalog per (tenant, environment) scope,
because its inputs are scoped that way (§3.1). Same concept everywhere,
different content per viewer.
Because it is derived and unpersisted, it is always in sync with the repositories by construction; that is not a property to maintain, it is a consequence of not caching. Do not materialise it (§8).
2. The five application kinds
Section titled “2. The five application kinds”| kind | what it is | example |
|---|---|---|
| app | a package with its own app.yaml | nextcloud, frappe |
| vapp | a template hosted by an app, instantiable many times | nextcloud/plugin |
| vapp instance | one installed instance of a vapp | ffx/erpnext |
| vpreset entry | a curated, pinned entry in a vapp’s catalog | talk, erpnext |
| app preset | a named var bundle for an app itself | (none exist, §4.2) |
The vapp itself is not a meaningful catalog application; a user picks talk or
erpnext, not “the plugin mechanism”. This was the owner’s starting point for
the visibility flag (§5).
3. What exists today, measured
Section titled “3. What exists today, measured”3.1 repo: scoped, prioritised, and adapter-capable
Section titled “3.1 repo: scoped, prioritised, and adapter-capable”ce/ent/schema/repo.go. Its own doc comment: “app catalog source repositories
scoped per (tenant, environment) with a priority ordering.”
Fields: name, url, token, priority, adapter, app_count,
synced_at, sync_interval, tenant_name, environment.
Unique index uq_repo_scope on (name, tenant_name, environment).
Edge To("apps") with ON DELETE CASCADE.
Consequences:
- Nothing is global. Two dimensions of scope, not one.
- Because uniqueness is scoped, the same repo name can exist independently in
different scopes with different URLs and tokens:
corp/prodandcorp/stagingcan each have their ownshc. tokenis per row, so a tenant can register a private catalog.priorityexists and is indexed; see the open question in §12 Q1.adapteris the origin-repo mechanism (coolify / umbrel / casaos / portainer / cloudron), which ingests a foreign platform’s whole app store and transpiles it at sync.
3.2 app: one row per app.yaml, and two unused columns
Section titled “3.2 app: one row per app.yaml, and two unused columns”ce/ent/schema/app.go, doc comment: “one row per app discovered in a repo.”
Fields: name, version, category, description, homepage, icon,
tags (JSON), source, repo_id, parent_app (String, Optional,
Nillable, not a foreign key), vapp (Bool).
The crawler (ce/daemon/services_seams_repo_crawler.go) “walks the synced repo
roots, parses each <root>/<app>/app.yaml, and REPLACES the repo’s rows
(delete-then-insert)”, and its catalogManifest struct reads parent_app and
vapp from app.yaml itself.
So the mechanism is: a whole app package may declare “I am a vapp of parent X.” And it is entirely unused:
app.yaml files declaring vapp: true → 0 (shc apps/ and ce builtin/)app.yaml files declaring parent_app → 0Therefore:
plugin.vapp.yamlproduces no row. The crawler never reads.vapp.yamlor.vpreset.yaml, onlyapp.yaml.- The two columns are half-wired plumbing: exactly the right shape for parent/child app modelling, never connected.
- No
vapp,presetorstackschema file exists inent/schema/.
parent_app being a soft string rather than an FK is probably correct, not an
oversight: the catalog spans independent repositories and app rows are
delete-then-insert, so a vapp in repo A may name a parent in repo B or one that
is absent. An FK cannot express that. The codebase already does this
deliberately elsewhere; deployment.pinned_node_id is explicitly FK-less so
that intent naming a departed node blocks nothing.
3.3 The published index is app-only
Section titled “3.3 The published index is app-only”Live index.yaml, 139,744 bytes, 77 apps at read time.
Top level: api_version, apps. Per app: archive, digest, version,
versions, channels, description, category, homepage, icon, tags.
- The string
presetappears nowhere in the file. - The string
vappappears once, as prose inside one app’s description.
So the repository index carries app-level display metadata (which is legitimately the app’s self-description) and zero structured vapp or preset data.
3.4 …but the archives do carry it
Section titled “3.4 …but the archives do carry it”scripts/build-apps-archives.go builds each .app as a filepath.Walk over
the whole package directory. So plugin.vapp.yaml and
plugin.vpreset.yaml are already distributed inside the artifact.
Archive sizes measured: 2,682 B (whoami) to 53,017 B (hyperswitch);
≈1.4 MB for all 77. Fetching every archive at sync is therefore cheap:
which matters for §6.
3.5 The only exclusion mechanism today is a name prefix
Section titled “3.5 The only exclusion mechanism today is a name prefix”if strings.HasPrefix(e.Name(), "test-") { // "They stay on disk for the e2e resolver; they never enter the // published catalogue."That is publication exclusion by filename convention, the wrong axis for a vapp, because excluding it from publication makes its presets uninstallable.
No hidden, listed, internal, visible or catalog field exists
anywhere in apps/*.yaml.
4. Presets and vpresets
Section titled “4. Presets and vpresets”4.1 What a preset is
Section titled “4.1 What a preset is”A named, versioned bundle of --var values plus display metadata
(docs/app-development/presets.md).
Resolution: version pick (explicit @version, else default; aliases
dereferenced; latest = highest semver key) → merge (vars base ⊕
versions[resolved] ⊕ operator --var, later winning) → persist (the
resolved version key is recorded in deployment state so re-renders and upgrades
stay symmetric).
meta schema: description, icon, homepage, category, tags, all
optional; tags/category feed shc preset search filters.
CLI already present: shc preset ls | show | versions | search, with the
reference noting remote-search behaviour. That is already a catalog
operation, filed under the wrong noun (§7).
4.2 Both files are documented; only one exists
Section titled “4.2 Both files are documented; only one exists”| file | scope | count in tree |
|---|---|---|
apps/<name>/preset.yaml | the app itself | 0 |
apps/<name>/<vapp>.vpreset.yaml | one vapp | 3, frappe, nextcloud, wordpress |
The presets doc’s own headline example is shc install wordpress --preset woocommerce, an app-level preset with no backing file in the tree.
WordPress has a vpreset and no app preset, so the primary documented example
demonstrates a capability with zero instances.
4.3 The structural limit that probably explains why zero app presets exist
Section titled “4.3 The structural limit that probably explains why zero app presets exist”A preset sets vars only. It cannot declare “…and also install these vapp instances.”
So “WordPress + WooCommerce as one tile” (the doc’s own example) is not expressible. You get a WordPress with some vars set, not a WordPress with WooCommerce installed. The obvious use case is the one the mechanism cannot do.
Making it expressible is a resolver change (a preset that composes vapp instances), not a data file. This matters before building the catalog, because it changes what a catalog application is. See §12 Q6.
4.4 Real use cases for app presets, grounded in this codebase
Section titled “4.4 Real use cases for app presets, grounded in this codebase”- Sizing. The doc’s canonical example (
worker_count). No other way to express small/medium/large except a wall of vars. - Vars that are only correct in combination. Live example found the same
day: mailcow’s
ssoTemplateMap+ssoLoginProvisioning+ssoDefaultTemplate. ShippingssoDefaultTemplate: Defaultmade the per-user mail switch decorative by handing a mailbox to every user the admin did not activate. A preset is precisely “these vars are valid as a set”; it turns a three-way footgun into one named choice. - Restore rungs. Already in use: the frappe vpreset carries
v15.59.0/v15.50.0labelled “the RESTORE rungs: the exact erpnext versions the frozen k8s benches were running.” - Postures.
sonarqube --preset auth-off; the frappebakeAppsbaked-vs-vapp mode. - Catalog tiles: a second browse application for one app with its own metadata.
4.5 Curation, and why it is the right default
Section titled “4.5 Curation, and why it is the right default”The owner chose the curated approach. The files are hand-authored with no
live upstream wiring; upstream is consulted at authoring time and the
answers baked in. The nextcloud vpreset records this in its own header,
including the URL it read (apps.nextcloud.com/api/v1/platform/<major>.0.0/apps.json
for majors 31–34, read 2026-08-04) and its ladder casualties as comments.
Curation is right because an unvetted upstream catalog flowing straight into
installs is worse, and because the unmaintained + acknowledged guard only
works when a human decided (pos_awesome is the precedent).
The cost is silent rot, which is why a freshness guard is being built:
nothing currently revalidates that a pinned git tag still exists or that a
Nextcloud app still has a release for the shipped major. Measured casualties:
externalpassword last rung 31; files_archive and
files_fulltextsearch_tesseract 32; metadata 33. (files_lock looks
like a fifth and is not; Nextcloud absorbed it into core.)
The guard’s important design point: those are correct today, broken later, so they must warn with the rung at which each dies and go red only when the shipped major passes it. A guard that reds on a future problem gets disabled.
4.6 Two preset defects found and fixed during this period
Section titled “4.6 Two preset defects found and fixed during this period”- Every nextcloud preset was inert and actively wrong. They set
app_idwhile the vapp declaresappId; preset vars merge by name, so the key was dropped and the vvars defaultcalendarwon.shc install nextcloud/talk --preset talkinstalled the calendar app, as did every other preset, and a preset-less install. - frappe presets defaulted to v16 refs on a v15 core (
9f4b332f7moved them to v16,df3935c9freverted the core, the presets were left behind), soshc install frappe/hrmswould land v16.15.0 on a v15 bench. Diagnosed by the restore inventory and fixed 2026-08-04, once the freshness guard turned it from an inference about version numbers into a measurement of upstream’s own admission rule:bench get-appenforces[tool.bench.frappe-dependencies] frappe = "<spec>"at the ref, and ten defaults named a ref whose spec admits nothing in the shipped 15 line. All ten were re-pointed at v15-admitting refs with the v16 refs left listed, and the guard was raised to report a v16-only default as BROKEN; as a WARNING it was indistinguishable from the twelve listed v16 pins that are refused by design, so the guard’s own first run reported all twenty-two together and exited 0.
There is no version knob for Nextcloud presets and the file does not pretend
otherwise: occ app:install/app:enable take no version; the store hands the
server the newest release admitting the running major. Hence one latest key
per entry; a per-rung versions: map would be four keys with identical vars
pretending to pin something.
5. Visibility: the hidden flag
Section titled “5. Visibility: the hidden flag”Owner’s proposal: apps and vapps listed by default; presets and vpresets not; with opt-out and opt-in in both directions.
5.1 A counter-proposal: derive the default from installability
Section titled “5.1 A counter-proposal: derive the default from installability”Measured: both vapps have required vars:
nextcloud/plugin.vapp.yaml: appId@string!frappe/plugin.vapp.yaml: name@string! url@string!So neither vapp is click-installable; a vapp tile needs a form where someone types a git URL. The vpreset entries are click-installable, because every var is supplied.
Proposed rule: default listed = “installable with no required free-form input.”
| kind | required input | proposed default |
|---|---|---|
| app | none (has defaults) | listed |
| vapp | appId! / url! | hidden |
| app preset | none | listed |
| vpreset entry | none | listed |
Mechanical, explainable, and checkable straight from the @…! markers. The flag
then handles exceptions in both directions, including deliberately
un-hiding the frappe vapp to offer an “install any Frappe app by URL” advanced
tile.
Resolved in Part II: the measured corpus is 11 vapps, not 2, which inverts this table’s vapp row for the majority, and the rule needed one refinement to avoid hiding half the catalog; see §17.4 and the ruling in §20.
5.2 Properties the flag must have
Section titled “5.2 Properties the flag must have”- Works at all three levels: app, vapp, and individual preset entry.
- Hidden ≠ uninstallable.
shc install <name>must still work.shc testis the standing precedent for “works, just not advertised.” - Orthogonal to
unmaintained/acknowledged: that gates installing; this gates displaying.pos_awesomemay reasonably be both. - It retires the
test-prefix hack (§3.5): fixtures carry the flag instead of depending on a filename, so a future app legitimately namedtest-somethingstops vanishing by accident.
5.3 The one thing that breaks “the catalog has no state”
Section titled “5.3 The one thing that breaks “the catalog has no state””The flag above is the author’s choice, living in the app’s files. An operator will eventually want to suppress something the author did not hide: “we don’t offer that to our tenants.” That is per-scope policy with no home in the app package, and it would be the first genuine catalog-layer state.
Natural home: the existing five-level scoped config cascade, a
catalog.hidden key at global / tenant / environment scope, rather than a new
table. Author’s flag and operator’s suppression compose, operator’s winning.
Worth designing in early; retrofitting a second visibility source later is how
you get two flags that disagree.
6. Where the catalog’s data comes from
Section titled “6. Where the catalog’s data comes from”The app layer is already fully derived from synced DB rows, with all the display metadata (§3.2). The vapp and preset layers are not; they live inside the archives (§3.4).
Two ways to close that, and the owner’s layering favours the first:
- Sync fetches and parses the archives. ≈1.4 MB for all 77, so cheap. Keeps
the repository dumb (it just serves apps) and the catalog derives everything
from local state. Needs no migration;
app.vappandapp.parent_appalready exist and are exactly the right shape; what is missing is the crawler emitting a row per vapp it finds inside a package. Since the crawl is delete-then-insert, those rows stay consistent automatically. - The repository projects each app’s declared contents into its index. One fetch, but every repository kind must implement the projection.
An earlier suggestion (“extend the index generator to emit preset entries”) is a violation of the layering, because the repository would start knowing what a catalog tile is. If projection is chosen, it must be framed as the app’s self-description (what is in this archive), not as catalog applications.
Presets would need the same treatment as vapps, or a third row kind.
7. Install vs catalog
Section titled “7. Install vs catalog”7.1 Install is already the primitive, and it is complete
Section titled “7.1 Install is already the primitive, and it is complete”It handles all of it today: shc install nextcloud (app), nextcloud@30+2
(exact rung), nextcloud/plugin --preset talk (vapp instance from a preset),
-i <plug>=<target> (integrations), --var overrides. There is no
--version flag; version is positional or @-suffixed.
Grammar: a bare token takes the newest revision of that line; omitting it means
latest. catalogVersionPredicate: a token containing + is an exact
match, a bare token is = OR LIKE '<v>+%'.
7.2 Install must not go through the catalog
Section titled “7.2 Install must not go through the catalog”- Install has to work with no catalog at all. Terraform’s
shc_deployment, the estate pipelines, CI, recover and restore never browse. Coupling install to a catalog would make all of them depend on a view existing and being fresh. - The catalog is a derived, unpersisted projection. Resolving through it would mean installing against a summary instead of the authoritative layer that carries digests, priority and version predicates.
7.3 The catalog’s source space is strictly smaller
Section titled “7.3 The catalog’s source space is strictly smaller”detectSourceKindForCLI (ce/modules/app/commands/source_body.go:50) returns
four kinds:
| kind | detected by |
|---|---|
| path | . / / / ~ prefix |
| archive | .tar .tar.gz .tgz .zip .bak .bkg .exp |
| git | git+ / git@ prefix |
| catalog name | anything else |
A catalog can only list what a repository publishes, so catalog ⊂ install.
Install must accept a local path, a git URL or an archive that no repository
knows about; that is how you develop an app, run a fork, or install something
private. (Same shape as helm: helm install ./mychart works and the index only
lists published charts.)
7.4 The catalog is a compiler, not a layer installs pass through
Section titled “7.4 The catalog is a compiler, not a layer installs pass through”A tile’s button should emit the install invocation a human would type
(exact pin, prerequisite, target) and then shc install executes it. Three
things that buys:
- Auditability. The UI action is a command you can log, paste, review, or put in terraform.
- One code path. No second install implementation to diverge. This codebase has been hurt repeatedly by exactly that: two backup engines with opposite defects, two SSO apps with one silently winning, a plug whose insert and update branches each half-wrote a config.
- The pin stays visible. The catalog must emit an exact
version+revision, neverlatest(§9.2). If it resolves internally, the drift hides.
Which makes the button a plan rather than a side effect: resolve, show,
then execute. That is the existing idiom (shc update --check, terraform plan).
7.5 Two install actions, not one
Section titled “7.5 Two install actions, not one”An app install creates a stack. A vapp-instance install adds an instance
to an existing stack. So there is no uniform button: “Install” vs “Add to…”,
and the second requires picking a target. A talk tile clicked with no
Nextcloud stack present must offer to install Nextcloud first.
That is a flow, not a metadata field, and it is the biggest consequence for any UI.
8. Freshness: three axes, only one free
Section titled “8. Freshness: three axes, only one free”| axis | mechanism | status |
|---|---|---|
| catalog ↔ local rows | derived on read | automatic, cannot drift |
| local rows ↔ repository | sync_all_repos cron (6 h), per-repo sync_interval, manual shc repo sync | silently failed for 3 days |
| preset refs ↔ upstream ecosystems | nothing | the freshness guard being built |
The middle row is not hypothetical: both estates’ repos were last synced 2026-08-01 12:00 because the task worker never drained. A derived catalog would have been perfectly, instantly in sync with a three-day-old world.
Therefore: the catalog must display synced_at per source on its face. A
derived view that does not disclose the age of its inputs is a lie with extra
steps.
Sync is periodic, not push, so bounded staleness is by design (same as
helm). If a cache is ever added for UI performance, the invalidation key already
exists as a column: repo.synced_at.
9. Identity, dedup, and pinning
Section titled “9. Identity, dedup, and pinning”9.1 Name collisions are real
Section titled “9.1 Name collisions are real”Measured: apps/mail exists as an app AND mail exists as a nextcloud
preset (plugin.vpreset.yaml:349; forms and news are similar). Flatten
apps and preset entries into one list and both search and install become
ambiguous.
So applications need qualified identity, mail vs nextcloud/plugin:mail,
regardless of how any surface chooses to draw them.
Related: flattening also discards parent_app, the column that makes
prerequisites and nesting work. The catalog should know the relationships;
flat-versus-nested is the UI’s choice, not the catalog’s definition. For the
third-party-ecosystem case the natural presentation is nested (“Nextcloud”
as a section with its 42 tiles beneath it) which also solves collisions
visually.
9.2 The install button must emit an exact pin
Section titled “9.2 The install button must emit an exact pin”The catalogue un-froze mid-roll on 2026-08-04: 123 → 282 apps, and
minio 2025.9.7+0 appeared, the build that permanently removes the admin
Console. Because a bare token matches = OR LIKE '<v>+%' and only
version+revision is exact, every unpinned deployment was a moving target.
A catalog whose button installs latest reproduces that incident per click,
at scale, on other people’s estates. The rule belongs in the single resolver,
not in each front end.
9.3 One catalog over many repos inherits the ambiguity problem
Section titled “9.3 One catalog over many repos inherits the ambiguity problem”Every estate has at least two repositories: the implicit builtin (crawled from
/usr/lib/shc/apps, shipped in the deb, no URL, cannot be unregistered) plus
registered HTTP repos. X409039APPAMB (the live system-postgres deadlock) is
two repositories offering the same app.
A catalog inherits that as two “Postgres” tiles, so the install action needs
a repository qualifier, which the master-tenant guard currently refuses for
system apps (X403979SYSSRC). So building the catalog needs that gap closed
anyway, and closing it also unblocks postgres 17/18 and gitlab 19.2.1.
digest (sha256:…, per version in the index) is resolution-layer integrity
and should survive into the tile rather than being dropped.
10. Two mechanisms for “list a third-party catalog as my own”
Section titled “10. Two mechanisms for “list a third-party catalog as my own””The owner identified vpresets as the mechanism for re-publishing someone else’s ecosystem as SHC apps. That is right, and there is a second mechanism at a different granularity:
| layer | ingests | produces |
|---|---|---|
repo.adapter | a foreign platform’s app store (umbrel, coolify, casaos, portainer, cloudron) | SHC apps |
| vpreset | a foreign app’s plugin ecosystem (apps.nextcloud.com, frappe’s GitHub) | vapp instances |
Nextcloud’s 42 store apps become plugin instances because they are plugins of an app. Umbrel’s catalogue becomes apps because they are apps. Same product idea, two levels, and a catalog would present both as tiles, which is the right outcome.
11. API shape
Section titled “11. API shape”11.1 Two namespaces, one API
Section titled “11.1 Two namespaces, one API”Not two services. shc.repo.* / shc.app.* for ground truth,
shc.catalog.* for the read model: same daemon, same generated client, one
auth model. Route pattern is already /api/method/shc.<module>.<method>.
11.2 It is not “UI ↔ catalog, CLI ↔ install”
Section titled “11.2 It is not “UI ↔ catalog, CLI ↔ install””There are four front ends over pkg/apiclient (283 methods, 345 mirrored
types): the CLI, the terraform provider, the MCP server, and the
HUD. An agent asking “what can I install here?” over MCP is neither a UI nor
a CLI, and is the consumer most likely to want resolve.
Both surfaces use both namespaces; they differ only in emphasis. The UI must call install to act, because the catalog resolves rather than installs. Building catalog as a UI-only API is how the UI grows its own install path.
A test for what belongs where: would two front ends have to agree on it?
Yes → catalog (pin selection, prerequisite computation, hidden filtering,
priority dedup, synced_at disclosure). No → UI (grid vs list, icon placement,
sort order).
11.3 The catalog namespace is read-only, which buys two things
Section titled “11.3 The catalog namespace is read-only, which buys two things”- It is safely cacheable at the HTTP layer.
- It can sit at a lower privilege than install, so a tenant user can browse what they cannot install.
Operator-side hiding (§5.3) is a config write, so it belongs in
shc.config.*, not catalog.
11.4 CE/EE
Section titled “11.4 CE/EE”Repositories and presets are CE (ce/ent/schema/repo.go, and the vpreset
files ship in the catalogue). So the resolver belongs in CE; a CLI-only
user should get browse and resolve without a licence. The graphical catalog is
the EE surface, matching the standing pattern (the fabric mechanism is CE
while Nebula is EE; the HUD and MCP are EE surfaces over CE machinery).
12. Open questions
Section titled “12. Open questions”Numbered for reference in further discussion.
Part II status: every question below except Q7 is resolved or ruled. Q1 → §29/§30: priority IS the disambiguator (§29 REVERSED §17.1/§21, which had said priority is dead weight; §30’s Ruling C then set the ladder: scope decides visibility, priority decides precedence, orthogonal). Read §29 and §30 for the live position; §17.1 and §21 are the superseded record. Q2 → §17.4/§20 (installability-derived default, refined, RULED). Q3/Q5 → §17.3/§22 (hybrid by repo kind; browse-only vapp rows). Q4 → §19 (implicitly YES, presets are a listed catalog kind). Q6 → §19 (dissolved by the taxonomy ruling: presets never compose). Q7: still the owner’s call, untouched. Q8 → §17.2 (measured: an empty shell, a daemon-local disk walk).
Q1: Is priority the answer to the ambiguity problem? The column exists,
is indexed, and the schema comment says repos are ordered by it. Yet
X409039APPAMB refuses when two repos match. Either priority is used for
something else, or it is an unused disambiguation lever that would break the tie
without needing repo qualification, which the master-tenant guard refuses.
Load-bearing, because it is blocking postgres 17/18.
Q2: What are the visibility defaults? Owner proposed apps+vapps listed, presets hidden. §5.1 argues for deriving the default from installability, which inverts it for the vapp/vpreset pair. Unresolved.
Q3: Where does the vapp/preset data come from: archive fetch at sync, or index projection? §6. Archive fetch is ≈1.4 MB and keeps the repository dumb; projection is one fetch but every repo kind must implement it.
Q4: Are app-level presets worth having at all? Zero exist. §4.4 argues yes for sizing and coherent postures (mailcow alone justifies it). The doc’s headline example is unbacked and should be fixed either way.
Q5: Should the crawler emit rows for vapps? It would populate the two already-correct columns and needs no migration. Presets would need the same treatment or a third row kind.
Q6: Should a preset be able to declare vapp instances? Today it cannot (§4.3), which makes “app + its plugins as one tile” inexpressible. This is a resolver change and it changes what a catalog application is, so it should be decided before the projection is built.
Q7: Is outbound LDAP a paid boundary? Adjacent, but it came up: inbound
LDAP federation into SHC is documented as the Pro→Enterprise boundary. Whether
serving LDAP outward is also a paid boundary is an owner call. (An ldap socket
was separately ruled no; demand measured zero, and the pruned MyVD face
served every realm anonymously. See docs/decisions/2026-08-05-ldap-socket.md.)
Q8: Does shc preset search’s “remote-search behaviour” already fetch
archives, or is there a remote preset surface not found in this pass? It sits
oddly against the finding that index.yaml contains no preset data.
13. The vApp-as-deployment debate
Section titled “13. The vApp-as-deployment debate”SUPERSEDED. After Part I was written, ce landed
c99b51c(“fix(app)!: a vapp instance stops getting a deployment row”), settling this debate in code on §13.1’s side, the reverse of §13.2/§13.3’s recommendation. See §18 for the incident record, the two-halves ontology that explains it, and the vdeployment naming ruling.
Included because it is the modelling question underneath the catalog, and because the conclusion reversed twice.
13.1 The case that a vApp instance is not a deployment
Section titled “13.1 The case that a vApp instance is not a deployment”In ground reality ffx/erpnext has no containers (shc status reports
SERVICES 0/0), no deployment directory, no compose project, no network and
no placement. What exists is an app installed into the frappe bench’s apps/
directory, a row in the site’s own tabInstalled Application, and files in a
volume. It is state inside another deployment.
And every time it inherits deployment semantics it breaks:
- v0.0.19 stamped
recorded_node_idon those rows → the daemon expected a directory that never exists → 12 rows flipped to degraded - the health rollup sees
0/0services and calls it unhealthy →shc lscan no longer express a healthy estate database.orphaned-stacksnow fails on the leader- the teardown code already carries the exception in prose: “a vApp has no top-level row and no app crons”
13.2 The case that it should be a deployment, and this one wins
Section titled “13.2 The case that it should be a deployment, and this one wins”- It has the entire deployment lifecycle. The row carries
status,pending_operation_id,app_version,app_digest,no_rollback,stopped,preset,preset_version, and every one of those applies. Splitting the table duplicates the async operation machinery, pin replay, drift detection, audit events, the RPC surface and the CLI verbs. - It genuinely is a deployment of an app.
app_namereadsfrappe/plugin; it resolves a version from a repo or preset; it runs integration jobs through its vsocket. To the resolver it is indistinguishable from a stack install; only where the bytes land differs. - Uniformity is what makes pins, backups, drift and recover work at all. A separate table means a second code path through every one, and this codebase’s worst bugs are all second code paths, which survive for weeks, whereas the forgotten-check bugs above were caught in one roll and fixed the same day.
- The parent/children FK with cascade is exactly right: uninstall the frappe stack and its instances go with it. A separate table needs the same FK anyway.
- Nullable-by-kind is an established idiom here:
pinned_node_idis nullable precisely because placement does not apply uniformly.
So the trade is: one table with a discriminator → bugs are forgotten checks; two tables → bugs are divergent implementations.
13.3 The actual defect: the discriminator is implicit
Section titled “13.3 The actual defect: the discriminator is implicit”There is no kind or type column on deployment. Yet the vApp-ness is
modelled, across three nullable columns: parent_deployment_id,
instance_name, and preset/preset_version.
So the discriminator exists but is spread out and unstated. Nothing says “I am a vApp instance,” and the invariant lives in a prose comment. That is exactly why three separate consumers forgot it.
Recommended fix: make the kind explicit and enforced: an additive kind
column (allowed under append-only, no rebuild) plus assertions at the three
sites that broke. Keeps all the shared lifecycle machinery, and converts
“forgotten check” into “test-caught.”
This is the same shape as two other fixes from the same period:
deployment_node split one overloaded column into anchored and observed;
the auth socket split one overloaded name into oidc and saml. Here the
overloading is a table whose rows mean two things, and the cure is naming
the difference, not separating the storage.
14. Corrections log
Section titled “14. Corrections log”Claims made during the discussion and later measured false. Recorded because the reversals carry more information than the conclusions.
-
“Presets have no
iconfield.” False: the documentedmetaschema includesicon. The three real files simply do not fill it. Not a schema gap; values to populate. -
“vapps are stored as first-class app rows with a parent pointer, so the nesting is already in the schema.” False. The crawler reads only
app.yaml; 0 app packages declarevapporparent_app;.vapp.yamlproduces no row. The columns are half-wired plumbing. -
“Extend the index generator to emit preset entries.” Violates the repository/catalog layering the owner articulated; the repository would start knowing what a tile is. Reframed in §6.
-
“Make
parent_appa real foreign key.” Wrong: cross-repo parentage cannot be an FK, since repositories are independent and app rows are delete-then-insert. The softness is correct; the emptiness is the defect. -
“A vApp instance is incorrectly modelled as a deployment.” Reversed after the owner pushed back. The table is right; the implicit discriminator is the defect (§13).
-
“No catalogue app needs SAML, so the socket split is hygiene.” False:
apps/mauticconfigures itself as a SAML SP against anopenid-connectclient, so Keycloak refuses the AuthnRequest with “Wrong client protocol” while both provisioning jobs print success. It was a live defect. -
“
deployment.parent_deployment_idanddeployment.instance_namehave zero writers and zero readers after this campaign; verified.” (Campaign handoff §2 item 4.) False for the first column and imprecise for the second, measured across both repos at ce39b7f5b/ shc4ec1e105a:parent_deployment_idhas three live readers, and ce main’s ownquota_slash_charges_stack_axis_test.gosays so in as many words (“StackModel.ParentDeploymentID itself STAYS; it still has live readers”):daemon/services_seams.go’sCountsForTenantvapp count,modules/health/reconcile’skeycloakStackEligible, and the three projections insubsystems/impl/stack_reconcile_ports.go. They read as inert only if you assume no legacy phantom row survives on a live estate; and promanager upgrades IN PLACE.instance_namehas zero consumers, but it is still mechanically written (as NULL) and read back bymodules/app/repository.go’s deployment UPSERT andselectStackCols. “No writer” and “written only as NULL” are different claims, and only the second one was true.- Both counts survive a non-vacuous grep: 2 571 Go files in ce, 2 220 in shc.
The readers that look like survivors (
ListVdeploymentBindings,ListVdeploymentRealms) read the vdeployment table’sinstance_name, not this one.
-
“Both dead columns can be dropped together in one Phase-2 slice.” False, and the obstacle is physical rather than editorial. SQLite refuses to drop a column a foreign key names, and
parent_deployment_idis named by the self-referencingdeployment_deployment_children; dropping its index first changes nothing:ALTER TABLE deployment DROP COLUMN parent_deployment_id-> error in table deployment after drop column:unknown column "parent_deployment_id" in foreign key definitionThere is no
ALTER TABLE DROP CONSTRAINTin SQLite, so the only mechanism that removes it is a table REBUILD, anddeploymentcarries nine inbound foreign keys, eight of themON DELETE CASCADE, which is what made the rebuild a measured data-loss event (deployment 3->1, service 1->0, host_mapping 1->0) and whymigrations/catalogue_shape_test.gorefuses the shape outright. The same cascade is now reproduced in-repo as a mutation probe: feeding the Atlas-generated rebuild to the real runner takesdeployment 3->2, service 1->0, host_mapping 1->0, port_mapping 1->0, vdeployment 1->0.instance_nameis the opposite case (named by no FK, no index, no CHECK) soALTER TABLE deployment DROP COLUMN instance_namesucceeds in place with foreign keys enforced and no child row moved. It went; the other stays, with its index, itsTo("children")edge and its three readers, until an owner ruling on how to rebuilddeploymentsafely on rqlite. Do NOT reason from theapp/presetprecedent: those were droppable because they have zero inbound FKs, which is the exact propertydeploymentlacks.
The recurring pattern in 2, 4 and 5: treating the presence of a column as
evidence of a populated, enforced relationship. Worth naming, because this
codebase has many half-wired mechanisms: the socket: key documented and read
by nothing, priority unused for disambiguation, DeleteAccessRole with no
caller, and the two columns in §3.2. 7 and 8 are its mirror image: treating
the absence of a reader as evidence that the column can go. A column is
removable when the schema permits it, and on this table only one of the two
did.
15. Related documents
Section titled “15. Related documents”docs/app-development/presets.md, preset format and resolutiondocs/app-development/plugs-and-sockets.md, thesocket:key (documented, now honoured)docs/decisions/2026-08-05-oidc-and-saml-sockets.md, the socket split, whose persisted-state analysis is the closest precedent for a catalog-side renamedocs/decisions/2026-08-05-ldap-socket.md, the LDAP rulingdocs/guide/operations/app-refresh.md, why a platform roll never touches running apps
Part II: the second session (2026-08-05, continued)
Section titled “Part II: the second session (2026-08-05, continued)”★ VOCABULARY NOTE, added at reconciliation. Parts II and III call a catalog entry a tile (28 occurrences) and, from §34.3, an
item. The owner subsequently ruled that the noun isapplicationand explicitly retireditemandentry; see §40, which is binding over this whole document. The older words are left standing in the prose below on purpose: they are the record of what was designed, built and shipped under them, anditemis still the wire spelling on cemaintoday. Read tile and item as application everywhere; §40.3 lists what the rename touches. This follows the discipline the corrections logs already set: mark the supersession, never rewrite the claim.Update 2026-08-05: the prose
itemusages were swept toapplicationin the gap-inventory cleanup pass (its §6 flagged that the ruling had landed while the prose had not followed). What still spellsitemis deliberate: direct quotes, the recorded rulings and corrections-log rows that document the conflict itself, and mentions of the ce wire spelling, which is real code until §40.3’s rename lands.tileis left standing per this note.
16. How Part II was produced
Section titled “16. How Part II was produced”The five empirically-resolvable open questions (Q1, Q2, Q3+Q5, Q8) plus §9.3’s
guard were measured by a 12-agent pass: one investigator per question, each
verdict independently re-derived by an adversarial verifier instructed to
refute it. Five verdicts survived; the Q6-adjacent one was corrected by its
verifier (§18). A second, smaller pass on the vdeployment-table question
(§26) followed. Baselines as in the header. Between Part I’s ce baseline
(9ed5af5) and Part II’s (c99b51c), ce landed the commit that settles §13:
see §18.
The owner then ruled on the judgment questions in discussion; each ruling is marked RULED below.
17. The measured answers
Section titled “17. The measured answers”17.1 Q1: priority is dead weight; qualification is the disambiguator
Section titled “17.1 Q1: priority is dead weight; qualification is the disambiguator”★ REVERSED by §29; the ladder is §30. The heading above is the superseded position, kept as the record of what was argued. §29 rejects this section’s reasoning by name: “priority isn’t wired into resolution” and “everything ties at 50” are implementation facts, not design arguments. Both have since been fixed;
BuiltinPriority = 10sits deliberately belowDefaultPriority = 50(ce modules/repo/types.go), so the tie this section measured no longer exists. The measurements below were accurate when taken and are retained for that reason; the conclusion drawn from them is not the live position.
The only functional read of repo.priority in ce is the repo listing order
(modules/repo/service.go:455, priority desc, name asc, feeding
shc repo ls and the Repo API). No resolution query joins on, filters by, or
orders by it. Both X409039APPAMB emission sites
(modules/app/install_runner.go:3336, modules/app/source_qualifier.go:129)
refuse on len(res.Repos) > 1 with no priority consultation, and the
historical pre-refusal silent pick was ORDER BY repo_id DESC, insertion
order, never priority (crawler comment, services_seams_repo_crawler.go:306).
A bolted-on priority-wins rule would also be inert on day one: builtin and
every registered repo sit at the same DefaultPriority = 50
(modules/repo/types.go:40, builtin.go:128).
The qualifier grammar, by contrast, is fully wired end-to-end:
<repo>/<app> (source_qualifier.go:156), a -r/--repo flag Part I did not
know about, and deployments persist RepoName so updates re-resolve pinned to
the same repo (install_async.go:502); ambiguity is a first-install-only
problem.
17.2 Q8: remote preset search is an empty shell
Section titled “17.2 Q8: remote preset search is an empty shell”The only remote path is --remote on preset search; it GETs
/api/method/shc.preset.search, whose handler runs the identical filesystem
walk of the daemon’s own paths.AppsDir() (ce/modules/app/router.go:1813 →
preset_loader.go:158). No archive fetch, no DB, no index, consistent with
index.yaml carrying zero preset keys, because preset data travels only
inside the .app tarball. On a released node /usr/lib/shc/apps contains
exactly the 4 system apps (shc .goreleaser.yaml:471; ce’s “~70 app dirs”
comment is stale), none with preset files, so production remote preset
search mechanically returns an empty set. §7’s “already a catalog operation
filed under the wrong noun” was conceptually right and mechanically wrong: it
reads no catalog data, so moving it under shc.catalog.* is a
reimplementation, not a rename. Side-finding: the endpoint has no
tenant-access check, the only sibling read handler without one.
17.3 Q3+Q5: the answer splits by repo kind (the either/or was a false frame)
Section titled “17.3 Q3+Q5: the answer splits by repo kind (the either/or was a false frame)”For builtin, git, and adapter repos, sync already leaves every package
file on disk (shipped roots; shallow clone under
<cache>/repos/<tenant>/<env>/<name>; the adapter’s -materialized sibling
tree); .vapp.yaml is already locally present and “archive fetch” is
free. For HTTP-index and registry repos (the kinds the live estates
use) sync downloads only the index body (4 MiB cap,
modules/repo/service.go:811); archives are fetched lazily at install
(materializeHTTPArchive, crawler:503). So fetch-at-sync is a new step only
for those kinds, and its primitives (fetchAppArchive’s retry ladder,
ExtractAppArchive) already live in the same crawler file. Two structural
facts settle the sub-questions:
- Delete-then-insert consistency holds only for rows written inside the
sync’s single transactional batch (both crawl paths open with
DELETE FROM app WHERE repo_id=?and run in onePool.Batch), so lazy install-time emission of derived rows is structurally wrong. Ruled out. - The
parent_app/vappplumbing is more wired than §3.2 said: the columns flow end-to-end through the index contract (HTTPIndexApp), the registry manifest sidecar and the shc generator, always empty. What no layer has is a per-app child list, which crawl-time parsing provides without touching any index producer.
Also measured: install-time materialization uses unguarded
http.DefaultClient (crawler:599) while sync’s index fetch rides
newGuardedHTTPClient, a pre-existing defect to fix when the sync-fetch
work touches those primitives.
17.4 Q2: the default is computable; the literal rule was insane
Section titled “17.4 Q2: the default is computable; the literal rule was insane”flattenVarDecls (ce/modules/app/detail.go:95) is the single @type!
grammar parser and yields Required and Default distinctly; everything it
needs ships inside the archive (nothing in DB rows or the index, which
itself pushes Q3 toward archive fetch). But the rule as Part I stated it
produces absurd results: 42 of 75 apps declare a required var with no
non-empty default, almost all integration wiring
(postgres.hostname@string!), so nextcloud, wordpress, gitlab, immich,
frappe and matrix would all default-hide while whoami listed.
The rescue is already in the codebase: ValidateRequiredVars
(vars_validate.go:68) exempts a required var whose group is
integration-satisfiable (the group has a matching <group>.plug.yaml, a
target selection, not free-form typing). With that refinement: exactly 11
apps hide (the 8 external-* shims, s3, gitlab-runner, vaultwarden),
all 76 vpreset entries list, the 3 typed-input vapps hide, and the 8 no-input
vapps list.
Two Part I errors this exposed (§24): the vapp population is 11, not 2, and
8 of the 11 default-LIST under the rule, inverting §5.1’s “vapp → hidden” row
for the majority, including s3/bucket, which a standing ruling says must
never be a tile. That inversion is the cleanest proof the derived default and
the manual flag are both needed. Also: the ! marker is parsed but
unenforced on the vapp install path (the lane branches at
install_runner.go:184, before the sole ValidateRequiredVars call at line
698), a §14-class defect, fixed structurally by the one-front-gate
architecture (§23).
17.5 §9.3’s guard: the framing survives; both of its stakes were stale
Section titled “17.5 §9.3’s guard: the framing survives; both of its stakes were stale”GuardMasterTenantDeploy (master_tenant_guard.go:134-155) refuses any
non-empty RepoName for master-tenant system apps, a check on request
spelling, pre-resolution. Corrections: (1) the system-postgres
X409039APPAMB deadlock was already closed at Part I’s own baseline by the
shipped-root precedence short-circuit (source_qualifier.go:117-121, a pin
equal to the shipped version resolves before the catalog is consulted, chosen
explicitly because the guard forbids qualification); (2) “closing it
unblocks postgres 17/18” was overstated; an unqualified explicit pin passes
the guard and resolves whenever exactly one repo satisfies it. What the guard
genuinely blocks is the catalog’s uniform “every tile emits repo_name”
contract. And a hole: with no post-resolution provenance assert, an
unqualified pin can already land a registered repo’s packaging in master.
Hence the ruling in §21.
18. §13 superseded: the two-halves ontology and the vdeployment ruling
Section titled “18. §13 superseded: the two-halves ontology and the vdeployment ruling”ce c99b51c (landed after Part I, measured on bitspur) settles §13 on
§13.1’s side. The v0.0.19 boot ran ImportOrphanManifests over vapp sidecars
for the first time, minted 12 degraded rows, and broke
database.orphaned-stacks on the leader; the fix removes the rows rather
than adding a kind column. At HEAD: an instance’s identity is its
vapps/<instance>/state.json sidecar; shc ls synthesizes the
<parent>/<instance> display row at read time; the orphan importer excludes
vapp sidecars fail-closed; a boot pass (PurgeVappInstanceRows) deletes any
rows earlier builds wrote; the invariant is mutation-tested.
The ontology that explains why this is right rather than merely expedient: the deployment lifecycle is two halves fused. The resolve half (name → repo → version pin → preset → vars → async operation) instances share completely, which is why they feel deployment-shaped. The run half (compose project, containers, network, directory, placement, quota, health) they have none of; their run half is the host’s. Every §13.1 bug was a run-half semantic leaking onto a resolve-half object.
RULED: the noun. The installed instance is a vdeployment; its parent
stack is its host. The v-family completes symmetrically:
app : deployment :: vapp : vdeployment (alongside vpreset, vvars, vplug,
vsocket). The name is unclaimed in both repos. The guardrail that travels
with it: a vdeployment is deployment-shaped, not deployment-stored; the
“v” is load-bearing; the name explains why there is no deployment-table
row and must never become an argument for re-inviting one.
Litmus test for future packaging: if it needs its own containers, network, or placement, it is an app, not a vapp, however plugin-shaped it looks.
Also corrected here (Part I §13.2): the claim that the preset columns on the
vapp row “every one applies” was wrong even before the rows were removed:
they were never populated for vapp rows; the only preset-column writer is
Phase-1 svc.Install (service.go:475-481), which the vapp lane bypasses.
The pin lives in the sidecar
(VappState.Preset/PresetVersion/PresetResolvedVars). Same §14 error class.
19. RULED: the taxonomy (Q6 dissolved, Q4 implicitly yes)
Section titled “19. RULED: the taxonomy (Q6 dissolved, Q4 implicitly yes)”A preset never composes; it wraps exactly one installable.
preset : app :: vpreset : vapp, each a named var-bundle around one thing,
and the parent-child relationship lives in exactly one place: the vapp
mechanism. Q6 asked whether a preset should declare vapp instances; the
answer is that composition was never the preset’s job.
| kind | what it is | catalog? |
|---|---|---|
| app | installable, becomes a deployment | tile (listed by default) |
| preset | var-bundle around an app | tile (listed) |
| vapp | the child mechanism, becomes vdeployments | tile only when input-free (flag overrides) |
| vpreset entry | var-bundle around a vapp, a curated vdeployment | tile (listed) |
| deployment / vdeployment | the installed results | never, results, not choices |
RULED: --preset is typed. An app token resolves the flag against the
app’s preset.yaml; a <parent>/<vapp> token against that vapp’s
.vpreset.yaml; never across. A vpreset applied to an app install is a
type error; its vars are vvars, meaningless to the parent.
Consequences:
shc install wordpress --preset woocommerce(the presets doc’s headline) is not merely unbacked; it is type-incorrect. The correct spelling isshc install wordpress/plugin --preset woocommerce. The doc must be fixed.- “App + its plugin in one click” is a flow, not a mechanism: the surface compiles a two-plan sequence (install the host, then the vdeployment) when no host exists. No composition semantics anywhere; the three heavyweight surfaces a composing preset would have demanded (declared-vs-installed reconciliation, restore intent-replay, composition drift) stop being requirements.
- The derived row kind gets simpler: presets and vpresets are structurally identical: (wraps: app | vapp, entry name, versions map, aliases, default, meta); one row shape serves both (§22).
- Q4 is implicitly ruled yes: presets are a listed catalog kind, so app presets should exist; mailcow’s only-correct-in-combination vars (§4.4) are the first candidate to author.
20. RULED: visibility (Q2)
Section titled “20. RULED: visibility (Q2)”Default: listed iff installable with no required free-form input, where
“free-form” excludes integration-satisfiable groups (§17.4’s exemption). The
author’s hidden flag overrides in both directions (§5.2’s properties stand,
including retiring the test- prefix hack). Operator-side suppression (§5.3)
needs no list-merge semantics: per-application boolean keys
(catalog.hidden.<qualified-application> at global / tenant / environment scope)
ride the existing config cascade with most-specific-wins per key, following
the crons.<name> override-grammar precedent.
On today’s corpus: 64 apps listed, 11 hidden (8 external-*, s3,
gitlab-runner, vaultwarden); 8 no-input vapps listed, 3 typed-input vapps
hidden; all 76 vpreset entries listed. s3/bucket must then be flag-hidden
per the standing “a bucket is never a tile” ruling, the proof the flag stays
load-bearing. Recorded honestly: “no required free-form input” ≠
“zero-click”; 31 listed apps still require an integration target selection,
which is §7.5’s flow, not a form.
21. RULED: identity and ambiguity (Q1, §9)
Section titled “21. RULED: identity and ambiguity (Q1, §9)”-
Identity is
(name, version, digest), not(name, version). Two repos offering the same name+version are either the same artifact (identical digest → collapse to one tile; deterministic repo choice: builtin first, else name order) or different artifacts (different digest → two tiles, loudly, digests on their faces, a supply-chain signal, never smoothed over). HTTP/registry rows already carry the digest in theirsourcefragment; builtin rows have none, and builtin-vs-HTTP is the case the shipped-root precedence rule already settles. -
Priority is dropped from the catalog’s shared logic (§11.2’s “priority dedup” dies). Qualification is the disambiguator; refuse-and-enumerate stays for bare names at the CLI, where it belongs.
★ REVERSED by §29; the ladder is §30. The owner ruled that priority is the disambiguator, the apt model, where a bare
apt install nginxis decided by pinning priority and qualification is the override. This bullet is the record of what was ruled BEFORE that and is no longer the position: priority ranks candidates (§30 step 3), scope decides only visibility, and the two are orthogonal. It is also live in code, not merely ruled;DefaultPriority = 50andBuiltinPriority = 10ince modules/repo/types.go, so the “everything ties at 50” premise §17.1 reasoned from is itself no longer true. What SURVIVES from this bullet is only the narrower kill §29 affirms:ORDER BY repo_id DESC, picking by insertion order, stays dead. Honouring declared operator policy is not the same sin as honouring an accident. Refuse-and-enumerate also survives, narrowed to §30 step 5: a genuine tie at the same scope and the same priority. -
Tiles emit the separate wire fields (
repo_name+app_name+ exactversion+revision(+ preset, + integration selections)) never the fused token (sidesteps the template-wins token ambiguity), neverlatest. -
Rule 3 reshapes to resolved provenance: instead of refusing the
RepoNamespelling, assert post-resolution that a master-tenant system app resolved from builtin. Strictly more coherent: admits explicit builtin qualification, keeps foreign packaging out of master, and closes the measured spelling-only hole (§17.5). -
Caveat recorded: repo-qualified resolution is daemon-only (
CatalogAppDirResolveris nil in the daemonless lane), so a tile-emitted plan needs a daemon, acceptable, since catalog surfaces are daemon-backed.
22. RULED: the data path (Q3/Q5 + D2 + D3)
Section titled “22. RULED: the data path (Q3/Q5 + D2 + D3)”- Hybrid by repo kind: builtin/git/adapter: crawl the already-local
roots for
*.vapp.yamland preset files; HTTP/registry: fetch head archives at sync (≈1.4 MB for the whole catalogue, riding the guarded HTTP client). All derived rows written inside the same delete-then-insert batch. Index projection is dead: the repository never learns what a tile is. - D2: vapp rows are browse-only. Keyed
(repo, parent_app, name)withvapp=true, stamped with the parent version they were parsed from; every resolution query filtersvapp=false; install always reads the.vapp.yamlfrom the parent’s actual archive. Display truth from rows, install truth from archives: collisions (fourdatabase, threeplugin, threebucket) are structurally impossible because nothing resolves vapp rows, and the version predicate never applies to them (they carry a format version, not a package version). - D3: parse the archive a bare
shc install <app>would resolve to: newest revision, default channel. One parse per app per sync; extend to per-channel heads only if channels become a browse dimension. Principle: the catalog describes what a click installs (pinned older estates never browse; they materialize their real archive at install). - Presets/vpresets are a third row kind (one shape for both, per §19): not app rows: ~36 entries with per-entry version maps cannot live in a single version column.
★ STORAGE SHAPE SUPERSEDED by §41. The owner later ruled one
applicationtable that sync INGESTS into, withkindas an explicit column, not vapp rows carried onappbehind avappbool plus a third row kind for presets. What survives unchanged is D2’s SEMANTICS: vapp rows are still browse-only, no resolution query adjudicates them, and display truth comes from rows while install truth comes from archives. Only the tables change. See §41.1 for the ruling and §41.2 for why D2 survives it; that is the non-obvious half, and reading “one table” as a repeal of D2 would re-open the collision hazard D2 closed.
23. The architecture, converged
Section titled “23. The architecture, converged”Repository: distribution, dumb, unchanged. Scoped rows; serves apps; the
.app archive is the transport for everything below app level; priority is a
display ordering.
Sync: the ingestion boundary (§22). Everything derived, batch-consistent.
★ “DERIVED, COMPUTED” SUPERSEDED by §41; “READ-ONLY” STANDS and is RATIFIED by §38. The paragraph below makes the catalog a computed query over the
appandpresettables. The owner ruled instead that sync ingests into anapplicationtable; the catalog is stored, not derived. Everything else in this section survives: read-only, per-(tenant, environment), the requirements-vs-satisfaction split, the compiler, one verb with two executors. The reasoning below is kept because it is what was actually built and shipped on cemain(modules/catalogstill queriesFROM app a JOIN repo randFROM preset p JOIN repo rat39b7f5b), and because the requirements-vs-satisfaction argument is independent of where the rows live.
Catalog: a derived, read-only, per-(tenant, environment) query. It
computes exactly the things two front ends must agree on: visibility (§20),
identity and dedup (§21), relationships (parent_app nesting; vpreset
entries under their parent), and disclosure (synced_at per source on its
face; §8 stands). CE resolver, EE graphical surface, lower privilege than
install. The catalog answers requirements (“talk needs a nextcloud
host”); the surface joins live deployment state for satisfaction (“you
don’t have one; install it first?”), which keeps the catalog pure and
§7.5’s two-button flow buildable.
The tile is a compiler (§7.4 stands): it emits a plan; shc install
executes it. One code path, auditable, pastable into terraform.
Install: one verb, one resolver, two executors. Install is already
polymorphic over sources (path / git / archive / name); this adds the second
axis: after resolution, a kind-tagged plan (kind: deployment | vdeployment)
picks the executor. The deployment executor is today’s stack path,
untouched. The vdeployment executor formalizes the vsocket as the host’s
content-hosting contract: assert host deployed and healthy → run the declared
jobs with the plan’s resolved vars → write the sidecar record → emit events;
uninstall mirrors. The integration-jobs engine is the mechanism; the
sidecar is the identity.
CLI UX is unchanged except for the slash, narrowed by §36: <app>,
<parent>/<vapp>, @version+revision, --preset, -i all keep their
meaning; dispatch moves from token spelling to resolved kind beneath the
grammar. One behavioral
delta, a fix not a change: the one front gate means required-var enforcement
finally applies on the vdeployment path: shc install frappe/plugin with no
url starts refusing properly instead of sailing past the unenforced !.
Why not a separate verb: it would be the second code path (two resolvers drifting, two validation sets, two audit shapes) and would break the compiler’s uniformity across the four front ends. The UX distinction (“Install” vs “Add to…”) is a surface concern compiling to the same primitive with different arguments.
24. Corrections log II
Section titled “24. Corrections log II”Claims in Part I measured false in Part II, same discipline as §14:
- §5.1 “both vapps”: the population is 11
.vapp.yamlfiles, not 2 (also true at Part I’s own baseline); only 3 declare required vars; the other 8 default-LIST under Part I’s own proposed rule, inverting its table for the majority. - §5.1 “neither vapp is click-installable”: nextcloud/plugin is: its vplug
falls back
appIdto the instance basename. - §5.1’s “app → required input: none (has defaults)”: false for 42 of 75 apps without the integration-satisfiable exemption (§17.4).
- §9.3 “the live system-postgres deadlock”: already closed at Part I’s own baseline by the shipped-root precedence fix; live only on pre-fix estates.
- §13.2 “preset columns … every one applies”: never populated for vapp rows; and the §13 debate itself was settled the other way (§18).
- §7/§12 Q8 “remote-search … is already a catalog operation”: it reads no catalog data anywhere (§17.2).
- The backup manifest’s
VAppInstanceRecordcapture is dead code, not capture-without-replay: nothing populatesStackContext.VAppInstances, somanifest.vapp_instancesis always empty. The working path is thevapps/sidecar subtree riding the host’s deployment tar and merging back on restore, preset pins included; what is missing is intent-level replay, not the record.
The recurring pattern, again: treating a column, flag, or documented
example as evidence of a populated, enforced mechanism. Part II’s fresh
instances: the preset columns (5), the dead capture (7), and the ! marker
unenforced on the vapp path (§17.4).
25. Legacy created or exposed by these rulings
Section titled “25. Legacy created or exposed by these rulings”- The
test-prefix publication hack → superseded by the author flag (§5.2). repo.priority→ drop (no-backcompat doctrine), or at minimum stop the schema comment implying resolution behavior it never had.shc preset search --remote+ its daemon endpoint → an empty shell in production AND unauthenticated; retire whenshc.catalog.*lands.- The
app.yamlvapp:/parent_app:keys (whole-app-as-vapp, zero users) → stop reading them incatalogManifest; the columns stay, fed by.vapp.yamlcrawling. The always-empty fields threaded through the index contract and registry sidecar become redundant at the same time. - Dead backup-manifest capture (
VAppInstanceRecord,StackRecord.Preset*/ParentDeploymentID/InstanceName) → remove; reintroduce only as real intent-replay if that ever ships. - Unreachable Python-era ports:
recordStackRow’s vapp-linkage branch (stack/service.go:802-810); theIsVappquota axis insvc.Installthat no vapp install can reach → delete. - Install-time materialization’s unguarded
http.DefaultClient→ fix with the sync-fetch work (same primitives). X403979SYSSRCas a spelling check → superseded by the provenance assert (§21).- Stale prose: ce’s “~70 app dirs” comment; the
IndexFromBytes“stub” comment; the CLI reference’s imaginary automatic daemon fallback for presets; the presets doc’s type-incorrect WooCommerce headline (§19).
Items 4–6 are worth doing early: they are exactly the half-wired plumbing class §14 identifies as how this codebase breeds false confidence: leaving them standing while the real mechanism is built alongside is how two disagreeing implementations happen.
26. Open questions II
Section titled “26. Open questions II”QII-1: Do vdeployments get their own table (FK to the host deployment), or stay sidecar-only? RESOLVED: yes, an own table. The owner leaned table-with-FK; a three-lane measurement (cluster-wide listing reality; the stack row/dir reconcile template; every sidecar consumer), with the listing verdict adversarially re-verified, confirms it is not merely preferable but required.
26.1 What was measured
Section titled “26.1 What was measured”Listing is node-local on every surface. The only vdeployment visibility
mechanism is DiskVappStackRows, a pure os.ReadDir walk of the serving
daemon’s StateHome()/deployments (ce modules/app/register.go:761), folded
in solely by listStacksHandler (router.go:403,425). The complete
internal-RPC registry (24 registrations enumerated) contains no list or
enumeration RPC, and sidecars are by design never replicated. So on a
multi-node estate: leader-served shc ls silently omits a
follower-hosted stack’s vdeployments (the fold is documented “best-effort”);
the x9s HUD and MCP dial one daemon and inherit its view; and shc status
shows vdeployments on no node at all (the health path has no disk fold).
The per-name stack.resolve peer fan-out cannot enumerate, and its receiver
reads only the top-level state.json, never vapps/.
Sidecar-only is actively broken today, three ways. (1) The leader-only
keycloak realm-adoption pass reads cross-node sidecar absence as an empty
exclusion set; it fails open: a keycloak host anchored off-leader gets
its keycloak/realm vdeployment realms adopted as SHC tenants (the
fail-closed contract covers read errors, not not-on-this-node). (2)
Concurrent installs of the same instance have no uniqueness point:
flat stacks get X409003STKEXS off the row plus a live-op check;
installVappAsync has neither, so two operations both run integration jobs
and the last WriteManifest wins. (3) The node-asymmetric listing above.
The codebase currently disagrees with itself. Half the index-consumer
set was already written against a row shape and then starved by
c99b51c: the HUD’s ListVappBindings self-join on
parent_deployment_id, the entire vapp quota surface (cap gate, usage
axis, tenant counts, Prometheus gauges, permanently zero), and the backup
manifest’s VAppInstanceRecord. Meanwhile recover/clone’s recordStackRow
still writes that shape into the deployment table and the boot purge
deletes it.
A separate table is structurally immune to the c99b51c incident
class. All four pathologies are welded to the deployment table itself:
stampNode and the occupancy anchor execute inside its writer, the health
poller enumerates only it, and the orphaned-stacks doctor SELECTs only from
it. Rows in a different table are invisible to every one of them by
construction, not by discipline.
26.2 The design
Section titled “26.2 The design”Table vdeployment: host_deployment_id FK → deployment with
ON DELETE CASCADE, instance_name (unique per host, the missing
uniqueness point), the vapp template ref, version pin, preset +
preset_version, lifecycle status + pending_operation_id (resolve-half
only), timestamps. Structurally excluded: recorded_node_id, occupancy,
service-health; the schema must be unable to express the run half.
The split the consumer map dictates: everything that executes stays on
the sidecar; everything that indexes reads rows. The sidecar remains the
execution record and the restore-bearing identity (it rides the host’s tar,
§24.7; cleanup replays its frozen PlugData/Discovery; the daemonless
protection guard reads it). The row is the replicated registry: it revives
the already-written consumers (HUD tree, quota axes, counts, terraform/MCP
per-instance status which today 404s or waits forever), gives
installVappAsync a real operation target plus the uniqueness point, and
lets the realm-adoption guard read a cluster-consistent registry instead of
the leader’s disk.
Machinery mirrored from the stack template: the vdeployment executor upserts the row on the placement node in the same operation that writes the sidecar; an additive, readiness-gated boot import (sidecar-without-row → add row, fail-closed); a doctor check (row-without-sidecar → prescription); uninstall deletes both; recover/clone uses the RMW pattern; the shc hand-written DDL mirror gains the table.
This completes c99b51c rather than reversing it: that commit removed
vdeployments from the wrong table; this gives them their own. The
invariant “no vdeployment rows in the deployment table” stands, the §18
guardrail holds, deployment-shaped, not deployment-table-stored, and
the name says why.
Q7 (Part I), outbound LDAP as a paid boundary, remains the owner’s call, untouched.
Part III: implementation, and the rulings it forced (2026-08-04)
Section titled “Part III: implementation, and the rulings it forced (2026-08-04)”Part II was design. Part III records what building it changed. Two of Part II’s conclusions were reversed during implementation: one by the owner catching a bad analogy of mine (§29), one by a gap the implementation surfaced (§30). Both reversals are recorded here rather than edited into Part II, per this document’s standing discipline.
27. What the campaign built
Section titled “27. What the campaign built”Five parallel lanes, each plan → three-lens adversarial review → TDD build →
three-lens independent verify. 42 agents, ~40 commits, every lane green on
its own tests, every lane pass-with-issues (the issues are catalogued in
§32). Branches are local campaign/*; nothing has landed.
| lane | delivers |
|---|---|
| install-core | the vdeployment table, the full rename incl. the on-disk one-shot, the executor’s row+sidecar write, the uniqueness point, the one front gate, boot import + doctor |
| guard-provenance | rule 3 from spelling refusal to resolved-provenance assert |
| catalog-datapath | browse-only vapp rows, the preset/vpreset row kind, guarded archive fetch at sync, the shc.catalog.* read model, the plan compiler |
| legacy-sweep | the stale-prose kill list and the §25.5-6 dead-code deletions |
| shc-adaptation | author hidden: flags, the test- prefix retirement, DDL mirror, doc truth |
Two verified properties worth recording because they were the campaign’s load-bearing risks:
- The
vdeploymentschema cannot express the run half (norecorded_node_id, no occupancy, no service health) with the unique index on(host_deployment_id, instance_name)supplying the uniqueness point that closes the measured same-instance install race. - The on-disk rename is a node-local one-shot with a marker ledger, atomic
os.Rename, and a collision rule that keeps both records and changes neither; it can lose nothing. It also handles a pre-rename archive restored after the boot pass ran.
28. Rulings III (owner, during implementation)
Section titled “28. Rulings III (owner, during implementation)”- R1: HOST READINESS: deployed only. The vdeployment gate asserts the
host exists (row/sidecar); it does NOT probe containers or health. A
stopped host fails its own vsocket job with the job’s real error rather
than a synthetic pre-check inventing a health opinion. The in-code
“assert host healthy” deferral becomes a decided contract.
Corollary the owner drew, and it is right by construction: a
vdeployment has no health checks at all: no containers, nothing to
poll. That is §18’s ontology, and it is why the v0.0.19 rollup calling
0/0unhealthy was a category error rather than a bad reading. - R3:
shc searchhides vapp template rows by default. Browse-only rows resolve to nothing, so surfacing them offers a name that cannot be installed. (A builder had made this call unilaterally; it is now ratified and pinned by a reason-stating test.) - R4: sync’s head-archive fetch uses bounded parallelism, not a sequential loop over hundreds of apps inside a daemon cron. Same guarded client, same per-app error isolation, same single batch.
- Repos are NOT stack-scoped. A repo is a source of things you can install; a stack is the result of installing. Scoping a source to a result inverts the dependency and could only ever supply one thing. What that would be for already exists: the deployment records the repo it came from, and that is the sticky source for its updates (§31).
29. REVERSAL: priority is restored as the disambiguator (§21 amended)
Section titled “29. REVERSAL: priority is restored as the disambiguator (§21 amended)”§21’s “drop priority; qualification is the only disambiguator” is
WRONG and is hereby reversed. The owner’s argument, which stands: this is
exactly how apt works: you type apt install nginx, never
apt install debian/nginx; when several sources carry it, pinning
priority decides; qualification (apt install nginx/bookworm-backports)
exists as an override.
My original reasoning does not survive scrutiny. “Priority isn’t wired into resolution” and “everything ties at 50” are implementation facts, not design arguments; both are fixable, and neither says the model is wrong.
The distinction I had conflated: what this codebase correctly killed was
ORDER BY repo_id DESC, picking by insertion order, an accident
deciding which packaging you get. Priority is declared operator policy.
Honoring policy is not the same sin as honoring an accident.
Consequence for the campaign: legacy-sweep’s two priority-drop commits are abandoned, not reverted; they simply will not land; its prose and dead-code commits land on their own.
30. RULING C: the resolution ladder
Section titled “30. RULING C: the resolution ladder”Answering “does repo scope override higher scopes, or just priority?”:
scope decides VISIBILITY, priority decides PRECEDENCE, and they are
orthogonal. Sources UNION (as apt does); a tenant-scoped repo must never
SHADOW the system scope, because registering one repo would then hide
builtin and break the platform stack.
Resolution order, now the contract, implemented as a readable ladder rather than an incidental SQL side effect:
- Visibility filter: candidates come only from the requesting
(tenant, environment)scope plus the system scope. Everything else is invisible: it cannot win, tie, or trigger a refusal. - Explicit qualification wins: the
-r/--repoflag restricts to that repo and stops (see §36; the slash is NOT repo qualification). An explicit operator statement outranks every heuristic below. - Priority ranks the survivors, highest first, and among equal top priority, the highest satisfying version wins (§36.2).
- Scope specificity breaks a priority tie: at equal priority the requesting tenant/environment scope beats the system scope, because the operator deliberately registered it there.
- Refuse only if candidates survive all of the above at the same scope
and same priority.
X409039APPAMBthen enumerates them, and its message must say the tie is operator-breakable (set a priority, or qualify) rather than merely “ambiguous”.
30.1 The tenant-isolation gap this exposed (measured)
Section titled “30.1 The tenant-isolation gap this exposed (measured)”While answering the scoping question I measured that registration is
scoped but resolution is not. catalogCandidates
(daemon/services_seams_repo_crawler.go ~496) selects
WHERE a.name = ? AND a.source IS NOT NULL AND a.source != '' with an
optional AND r.name = ? and no tenant_name/environment clause:
while the repo table’s unique index is (name, tenant_name, environment)
and builtin sits at the sentinel scope system/system.
So today one tenant’s privately-registered repo (with its own token) can supply an app to a different tenant, and the ambiguity refusal can be triggered by a repo the installing tenant cannot see. A derived catalog built on this would put another tenant’s private apps on a viewer’s tiles. Rung 1 of the ladder closes it.
31. RULING D: update stickiness with graceful fallback
Section titled “31. RULING D: update stickiness with graceful fallback”An update PREFERS the repo the deployment was installed from, and falls
back only when that is genuinely unavailable. The sticky half already
exists (the recorded RepoName pins the re-render); what was missing is
the graceful half: today the pin is rigid, so a vanished repo strands the
deployment.
- Try the recorded repo first, within the visible scopes.
- Fall back to the §30 ladder if it is gone, no longer visible in scope, or no longer carries a satisfying version.
- A fallback that changes provenance is announced: log, event, and the new repo recorded. Never silent. This follows §21’s surviving principle that a provenance duality is displayed loudly rather than smoothed over.
32. Orchestrator arbitrations (mine, not the owner’s)
Section titled “32. Orchestrator arbitrations (mine, not the owner’s)”- All §25.5-6 dead-code deletions belong to legacy-sweep. install-core
declined them as legacy-sweep’s, legacy-sweep declined them as
duplicated, and the result was that nobody deleted them, a standoff
produced by two plans naming the same symbols. install-core’s already
landed
QuotaScope.IsVapp→IsVdeploymentrename stays (a genuine prerequisite of its quota axis); legacy-sweep builds on top. - A duplicate-symbol collision invisible to git: install-core and
catalog-datapath independently declared
InstallPlanKind,KindDeploymentandKindVdeploymentin packageappin differently named files. Both merge cleanly; the package then fails to compile. install-core’s richer version wins; catalog-datapath’s file is deleted. Worth recording that the two builders converged on the same names and the same §18 rationale independently. - Landing order and the collision classes are recorded outside this
document, in the campaign’s
LANDING.md. The measured result: the entire cross-lane conflict surface is generated artifacts (ent/*,atlas.sum); no hand-written file conflicts. A merged install-core + guard-provenance tree builds clean and the guard’s assert still fires on the reshaped dispatch, the campaign’s single riskiest interaction, measured rather than assumed.
33. Still open
Section titled “33. Still open”- Guard scope: RULED in §35: assert at every resolution. (My first-render-plus-doctor recommendation was superseded by the owner’s observation that a bare re-render resolves nothing at all.)
- Q7 (Part I), outbound LDAP as a paid boundary.
- The unbuilt remainder at the time of writing: install-core’s B7 wire rename (gated on the shc half landing in the same window), shc’s pin- coupled tranche C, and the doc-set two-noun window that closes with it.
34. The catalog API: shape, vocabulary, and what it refuses to do
Section titled “34. The catalog API: shape, vocabulary, and what it refuses to do”Framing the owner chose, and it is the right one: the catalog API is the set of operations a software store performs. That framing is what exposed the gaps below.
34.1 The boundary
Section titled “34.1 The boundary”Three namespaces, and a store composes all three:
| namespace | answers | examples |
|---|---|---|
shc.catalog.* | choices | browse, search, detail, compile, updates-available |
| deployment / vdeployment | results | what is installed, its status |
| install / update / uninstall | actions | execute |
Uninstall is NOT a catalog operation, and the reason is stronger than “it doesn’t need one”: uninstall acts on a result, which already carries everything needed to destroy it (its dir, its sidecar, its host, its protection flag). The catalog application that produced it may no longer exist; repo unregistered, version unpublished, listing hidden. An uninstall that consulted the catalog would become unable to remove things exactly when you most need it to. Same reason install must work with no catalog at all (§7.2).
34.2 What is built
Section titled “34.2 What is built”shc.catalog.list (read-only, tenant-confined, per (tenant, environment))
and the compiler. The compiler abstracts the application KIND, which is the point:
a surface hands it one catalog application and gets back the concrete
invocation(s), never needing to know whether the application was an app, an
app+preset, a vapp, or a vpreset entry. A tile whose host is missing
compiles to TWO invocations rather than a branch inside one.
It consults no deployment state: the catalog answers requirements (“talk needs a nextcloud host”); the surface joins live state for satisfaction (“you have none; install one first?”). That split is what keeps the catalog a view rather than a second install path.
34.3 Naming
Section titled “34.3 Naming”-
RULED (owner): the listed things are
items, catalog items. The request field already spells ititem; it stays. Considered and rejected:app(one of the four kinds an item can be),package(taken by the.apparchive, and wrong for a vpreset entry),entry(taken one level down by “vpreset entry”),listing,product.★ SUPERSEDED by §40. In a concurrent session the owner ruled the noun is
applicationand retireditemandentryby name: “they say where a thing sits rather than what it is”. This bullet is the record of what was ruled and shipped BEFORE that:itemis the wire spelling on cemainat39b7f5b(modules/catalog/types.go:type Item struct/Items []Item, whose own comment reads “Item is one tile”), so the rename is owed work, not a documentation edit. The rejection reasoning above SURVIVES and is reused by §40:app,packageandentrywere rejected for reasons that hold equally against them, andapplicationis the word that clears all three objections plus this bullet’s own. -
planis retired as the compiler’s noun. Two reasons. (1) SHC sells TIERS; in any store context “plan” reads as subscription plan, which is the wrong meaning in exactly the surface this API is for. (2) It borrows terraform’s connotation, where a plan is a DIFF AGAINST EXISTING STATE, and this deliberately consults none, so the word trains the wrong expectation. Replacement: the endpointshc.catalog.compilereturninginstalls[]of typeInstallInvocation, which keeps §7.4’s “the tile is a compiler” claim visible on the wire and uses, for the elements, the same noun the user and the executor already use.
34.4 Integrations are PASSTHROUGH (owner ruling)
Section titled “34.4 Integrations are PASSTHROUGH (owner ruling)”The caller supplies the integration selections; the catalog never invents a target. Reasons beyond taste: choosing which postgres is a policy decision the catalog cannot make when two are equally valid; an integration edge is consequential enough that a revoke verb exists for it; and it is the same requirements-vs-satisfaction split as the missing-host case, so the system has one rule rather than two. A missing dependency therefore behaves exactly like a missing host: “you have no postgres, install one first?” as a second invocation, never an automatic provision.
But the catalog must DECLARE the requirement even though it will not satisfy it: which plugs are required, and which groups are integration-satisfiable. Otherwise every front end re-derives “what does this app need” from the archive, which fails §11.2’s two-front-ends test. This is nearly free; the visibility rule (§20) already computes exactly this data, since “installable without free-form input” IS required-vars minus integration-satisfiable groups.
34.5 Versioning across the four kinds
Section titled “34.5 Versioning across the four kinds”A vapp template has no version of its own. .vapp.yaml carries a
FORMAT version (1.0), the schema of the file, not the thing it installs.
A vapp ships inside its parent’s package, so its version IS the parent’s.
That is why vapp rows are stamped with the parent version they were parsed
from and the version predicate never applies to them (§22 D2).
Presets and vpresets DO have their own versions (a versions: map, a
default, aliases, latest = highest semver key) and the resolved key is
persisted beside the app pin. Three independent axes, and conflating them
is where the bugs live:
- Artifact version: the package’s
version+revision; what the repo publishes, what the digest identifies, what pins the bytes. - Preset version: which var bundle you get.
- What the vars POINT AT: e.g. a git ref for a frappe app. Not a version in any registry sense; nothing pins it.
The owner’s insight (“a vapp might have a version in the vvar”) is
exactly axis 3, and the frappe vpreset already resolves the tension by
convention: its version KEYS are the upstream versions (v15.59.0,
v15.50.0, the restore rungs). So the preset’s own version map is where
“which version of the thing this entry installs” is expressed, and a
store’s version selector reads it directly. Where upstream has no
selectable version the honest representation is a single latest key,
nextcloud, because occ app:install takes no version at all; a per-rung
map there would be four keys with identical vars pretending to pin
something.
The hazard: the axes are coupled and have already broken. The frappe
presets once defaulted to v16 refs on a reverted v15 core, so
shc install frappe/hrms would land v16.15.0 on a v15 bench; each axis
individually valid, the PAIR wrong. A compiled invocation pinning both
halves together helps but cannot detect incompatibility; validating the
PAIR is the freshness guard’s job (§4.5), and the nextcloud rung casualties
are the same class from the other direction.
34.6 The API’s last two questions: RULED, see §35
Section titled “34.6 The API’s last two questions: RULED, see §35”shc.catalog.updates: YES, shaped exactly like install (compile, never
execute). shc.catalog.apply: DEAD; there is no install that does
multiple installs, and the owner’s integration analogy settles it.
35. Rulings V: the ledger closes (2026-08-04)
Section titled “35. Rulings V: the ledger closes (2026-08-04)”The owner’s answers to the final four open decisions. Two corrected the agent’s recommendations.
35.1 Guard: assert provenance at EVERY resolution (supersedes §33’s rec)
Section titled “35.1 Guard: assert provenance at EVERY resolution (supersedes §33’s rec)”The owner’s premise, confirmed against modules/app/package_pin.go’s own
prose: the materialized app package rides locally with the deployment,
and MaterializeCatalogDir returns that local dir unconditionally when it
exists, so a bare re-render consumes recorded bytes and resolves
nothing. Re-resolution happens only when the platform genuinely goes back
to a repository: a version-changing update, refresh_app_package=true, a
node move, a re-render on a node that never held the cache, the §31 sticky
fallback. And recover never resolves at all (§35.3).
Therefore: guard every resolution event, not just the first render. This closes §17.5’s hole completely, and the outage scenario that drove the agent’s first-render-only recommendation cannot occur: a bare restart resolves nothing, so it cannot be refused. The doctor check becomes optional rather than load-bearing.
35.2 shc.catalog.updates: yes, and it is install’s symmetric twin
Section titled “35.2 shc.catalog.updates: yes, and it is install’s symmetric twin”Owner: “wouldn’t catalog update wrap shc update just like install wraps
shc install.” That symmetry IS the ruling: the catalog computes what is
updatable (the newer exact pin in a visible repo, whether updating would
change provenance, synced_at for staleness disclosure) and compiles
the update invocation; execution goes through the ordinary update entry
point. The catalog still never executes anything.
35.3 catalog.apply is dead, and recover is repo-free by design
Section titled “35.3 catalog.apply is dead, and recover is repo-free by design”Owner: there is no install that does multiple installs; you install the host first, then the vapp, exactly the way an integration expects its socket app installed before the plug connects. The two-invocation sequence is a client flow, not a server primitive.
The one operation that “does it all” is recover, and the owner stated the boundary principle worth recording permanently: recover never uses the repository or the catalog. It rebuilds from the backup’s own app package, “the only safe way to do it”, and only subsequent updates may consult a repo again. So the catalog serves acquisition (new installs, version changes); recover, restore and bare re-renders live entirely on recorded local bytes. This is §7.2’s install-works-without-a-catalog rule, extended to its strongest form.
35.4 hidden: vs private:: two keys, two meanings
Section titled “35.4 hidden: vs private:: two keys, two meanings”The dual-meaning hidden a verifier caught in the shc publisher is
split. hidden: true = catalog visibility only; never affects
publication or resolution (§1’s load-bearing rule). private: true =
excluded from publication entirely, the publisher’s concern, and what
test fixtures carry (completing the test- prefix retirement, §25.1). An
author who hides an app keeps it installable; an author who marks it
private keeps it out of the repository altogether.
35.5 Plural preset filenames
Section titled “35.5 Plural preset filenames”presets.yaml (app level, bare, because a package holds exactly one
app, so a prefix would repeat the directory name) and
<vapp>.vpresets.yaml (prefixed, because a package may host several
vapps). Plural in both cases, matching vvars, whose precedent already
broke the singular-type-marker reading of the suffix family.
35.6 vpresets are convention-driven, and the convention gets written down
Section titled “35.6 vpresets are convention-driven, and the convention gets written down”The owner named the design accurately: the mechanism is only a named var
bundle with a version map; everything ecosystem-shaped is authoring
convention. The convention, currently tribal and responsible for two
production bugs, gets documented in docs/app-development/ as the
plugin-vapp authoring contract:
- declare the vvars in the vapp; every preset var name must match a
declared vvar exactly (the inert-nextcloud-presets bug:
app_idvsappIdsilently dropped the key and every install gotcalendar); - per-entry constants in
vars, per-version deltas in the version overlay; - version keys mirror upstream’s own identifiers when upstream is
selectable (frappe’s git tags); a single
latestkey when it is not (nextcloud; a per-rung map would be identical vars pretending to pin); - name a
default; fillmeta, because that is literally what the catalog renders.
Two conventions get promoted to enforced validation, because both have already failed silently: the vvar-name match, and pinned-ref existence (the freshness guard’s pair-validation, §4.5/§34.5).
36. Rulings VI: the grammar narrows and the ladder learns versions
Section titled “36. Rulings VI: the grammar narrows and the ladder learns versions”Recorded late: the implementation cited both of these as settled while the
document still taught the old grammar. The rulings are real (owner-given in
discussion, built and tested on campaign/priority-scoping); this section
is the amendment the code’s citations point at.
36.1 RULING E: the slash means <parent>/<vapp>, only
Section titled “36.1 RULING E: the slash means <parent>/<vapp>, only”shc install foo/bar used to be context-dependent: “app bar from repo
foo” OR “vapp bar of parent foo”, disambiguated by a carve-out where a
<child>.vapp.yaml under a resolvable parent won. That heuristic depends on
what happens to be installed and what the repos happen to contain; name a
repo nextcloud and the readings collide head-on.
The slash is now always parent/child. Repo qualification is the
-r/--repo flag, exclusively. Both spellings already existed, so this is
a NARROWING, not new machinery, and the vapp-wins carve-out is DELETED
rather than refined: no token’s meaning may depend on catalog contents.
Rationale, preserved: <app>/<vapp> is the common user-facing operation
(talk, erpnext, a database); naming a repo is the rare deliberate override,
which is what a flag is for. apt does not rescue the positional form:
it spells its override nginx/backports, package-then-source, which
would collide with nextcloud/talk just as badly.
Corroboration worth recording: the terraform provider had already ruled
this way for itself. shc_deployment rejects any slash in app with its
own “CLEAN BREAK” note and carries a separate repo attribute
(deployment_resource.go:433). The CLI was the outlier; this aligns it.
Catalog-emitted invocations were never affected; they carry repo_name
and app_name as separate wire fields (§34.2).
36.2 The version rung: priority is the override, version the default
Section titled “36.2 The version rung: priority is the override, version the default”§30 rung 3 said only “priority ranks the survivors”, which left the most consequential case unstated: repo A at priority 50 with postgres 15, repo B at priority 10 with postgres 18.
Highest priority wins; among equal top priority, the highest satisfying version wins. That is apt’s own shape: every normal source shares a priority, so version decides by default, and pinning exists precisely to override version. Without the clause, two repos at equal rank carrying different versions would REFUSE where apt resolves, and a builder could implement it either way.
Rung 5’s refusal therefore fires only at a same-scope, same-priority, same-version tie, genuinely different packaging of the identical artifact identity, which is exactly when a human should look.
36.3 Where these leave the ladder
Section titled “36.3 Where these leave the ladder”- visibility filter (scope) → 2. explicit
-r/--repo→ 3. priority, then version → 4. scope specificity → 5. refuse. Digest collapse (§30 rung 0) removes same-artifact mirrors before adjudication, so a refusal always means different bytes.
Part IV: the concurrent session’s rulings, reconciled (2026-08-04/05)
Section titled “Part IV: the concurrent session’s rulings, reconciled (2026-08-04/05)”A second session ran in parallel with Parts II and III and produced its own
§16–§21 at this same path, landed on shc main as three commits: 08197dfa3
“four owner rulings turn the proposal into a buildable contract: read-only,
one query surface, and the App Store is the consumer”, bfa099a43 “the thing
in the catalog is an application, and the app/application trap is made
inexpressible”, and fba642a30 “one application table, hidden rows are
synced, and the archive is not the row”. Those rulings are folded in here,
renumbered so the larger record’s numbering survives. Three things to know
before reading:
- Most of it RATIFIES Parts II/III rather than adding to them. Where a ruling is already carried by a Part II or Part III section, this Part says so and points at it instead of restating it. That mattered enough to be the reconciliation’s main risk: “already covered” is the claim that silently drops a ruling when it is wrong, so every such verdict below names the section and the sentence that carries it. §44 tabulates all of them.
- Two rulings genuinely CONFLICT with Parts II/III: the noun (§40) and the storage shape (§41). The owner’s word is the tiebreak in both. The superseded reasoning is kept and marked, never deleted, the way §14 and §24 already work.
- Several rulings are genuinely ADDITIVE and load-bearing: the store’s API requirements (§37), the measured argument for one mutating path (§38.1), the synthetic-progress trap (§38.4), the CLI surface map (§39), the inexpressibility guard (§40.1), and the invisible-package gap (§42.1). None of these appears anywhere in Parts I–III.
37. THE PURPOSE, stated by the owner: this is the API a future App Store consumes
Section titled “37. THE PURPOSE, stated by the owner: this is the API a future App Store consumes”“That’s what I mean by the catalog. Like the apis necessary for a future App Store to use.” The UI is explicitly out of scope; this is about what the API must expose so a store could be built against it without reaching into the primitive layer.
Verdict: the FRAMING is already covered. §34 opens with the same framing from the same owner (“the catalog API is the set of operations a software store performs”) and §34 credits that framing with exposing its own gaps. So this section does not introduce the frame; it enumerates what the frame demands, and that enumeration is the additive part.
37.1 What a store needs, beyond a flat list
Section titled “37.1 What a store needs, beyond a flat list”Each row is a requirement on the API, not a UI concern. The right-hand column records whether Parts II/III already answer it, measured, not assumed.
| need | why it is an API concern | status in Parts II/III |
|---|---|---|
| A detail read that returns the INSTALL CONTRACT | A store renders a form before installing. It must know the required vars and their types (apps/frappe/plugin.vapp.yaml declares name@string! and url@string!; apps/nextcloud declares appId@string!) and the required plugs, or the install fails after the user commits. | Half covered. §34.4 rules that the catalog must DECLARE which plugs are required and which groups are integration-satisfiable, and §17.4 measures flattenVarDecls as the one @type! parser yielding Required and Default distinctly. Neither states the typed var list itself as an API field. That half is ADDITIVE. |
| Categories and tags as first-class | Browsing 282 apps without them is a search box and nothing else. The published index already carries category on all 77 apps and tags on 66, exposure, not new data. | ADDITIVE. category/tags appear in Parts I–III only as schema field lists (§3.2, §3.3, §4.1) and as shc preset search filters. No section makes them a catalog API requirement. |
| Pagination and a stable sort | 282 apps and 375 versions. A store paginating over a listing whose order is not stable double-shows and skips entries. | ADDITIVE. Nothing in Parts I–III mentions pagination or listing-order stability. |
| Stable identifiers for deep links | A store links to an application and to a specific version. §9’s identity question decides whether a bookmark survives a repo re-sync. | Mostly covered. §21 rules identity is (name, version, digest); §41.1’s qualified column stamps the one identity string every surface spells. The deep-link survival framing is the additive part, and it is the sharpest argument for stamping identity at ingest rather than recomputing it per reader. |
| Versions per application, with what each renders | Every published revision now records the images it renders, so a store can show what a version actually installs rather than a label. | Covered. §34.5 rules versioning across all four kinds and separates the three axes; §41.5’s archive + digest + per-version images split is where the data lives. |
hidden honoured everywhere | A store must never surface a hidden vapp while the preset that uses it stays listed. | Covered and refined. §20 rules the derived default with the author flag overriding both ways; §35.4 then splits the dual-meaning key into hidden: (catalog visibility) and private: (excluded from publication). |
| ”Can I install this here?” | Entitlement and tenant scope. An application a tenant cannot install should be distinguishable from one it can; a store that offers an install which then refuses is worse than one that greys it out. | Split. The TENANT half is covered hard: §30 rung 1 is the visibility filter and §30.1 measures the exact isolation defect it closes. The ENTITLEMENT half is ADDITIVE; entitlements are not mentioned anywhere in Parts I–III. |
37.2 What this framing settles
Section titled “37.2 What this framing settles”Three of these are settled harder elsewhere and are recorded here only so the chain of reasoning survives:
- §7 install-vs-catalog: a store consumes the catalog and can only install what a repo carries; the primitive install keeps path/archive/git for operators. The catalog is the narrower surface, deliberately. §35.3 later extends this to its strongest form: recover and restore never consult a repo or the catalog at all.
- §5 visibility:
hiddenis a store-facing concept, so its default belongs to what a storefront should show, not to what an operator can reach. §20 rules exactly this and §17.4 measures the corpus it applies to. - §4 curated vpresets: curation exists so a listing renders without fetching upstream; a browse page cannot make N upstream calls. That is why the metadata must be complete in the package, and §35.6 turns the tribal convention into a written authoring contract.
- Q1 (repo
priority): a store needs one answer per name, but a silent winner is what the crawler’s oldORDER BYdid. Reconciled in §43.2: §29 restored priority, §30 and §36 built the ladder, and the answer is deterministic and stated.
37.3 What it does NOT license
Section titled “37.3 What it does NOT license”ADDITIVE, and it is a scope fence worth keeping. Not the UI, not a web storefront, not HUD panels. And not screenshots, ratings, install counts or any social surface; none of that exists as data anywhere in the packages today, and inventing fields the packages cannot fill is how a listing starts lying. If a store wants them, they become a packaging contract first.
This fence is also the reason the noun tile loses in §40: a tile is a
rendering, and this API does not license a renderer.
38. RATIFIED: the catalog is READ-ONLY. Install and update stay on the regular API.
Section titled “38. RATIFIED: the catalog is READ-ONLY. Install and update stay on the regular API.”The owner’s reasoning: the CLI does not need a different way to install, so there is no need for catalog install/update endpoints. A future store calls the SAME install/update API the CLI and the terraform provider already call. The catalog’s job is to say what is available and what to do with it, nothing that mutates.
Verdict: COVERED, precisely, in three places. §34.1’s boundary table already
partitions choices / results / actions and rules that uninstall is not a
catalog operation with a stronger reason than “it doesn’t need one”. §35.2
rules shc.catalog.updates as install’s symmetric twin that compiles and
never executes. §23 already calls the catalog read-only. So this section
ratifies rather than decides, and it contributes the argument the earlier
sections lacked (§38.1) plus a trap nobody had recorded (§38.4).
★ The wording trap, resolved. The concurrent session’s text ends with “No
catalog install endpoint. No catalog update endpoint.” Read literally that
deletes shc.catalog.updates, which the owner ruled in and which is built and
shipped on ce main. It does not. The ruling forbids a mutating endpoint;
shc.catalog.updates computes what is updatable and compiles the invocation,
and execution goes through the ordinary update entry point (§35.2). The honest
statement of the ruling is: no catalog endpoint executes anything, and no
catalog-side job orchestration exists. The surface is list / search / get /
versions / compile / updates, all read or compile, none executing.
38.1 ADDITIVE: the measured argument for exactly one mutating path
Section titled “38.1 ADDITIVE: the measured argument for exactly one mutating path”This is the strongest justification in either document and it appears in neither
Part II nor Part III. Two mutating paths must independently enforce required
plugs, entitlements, quota and job execution, and they drift. This project
has already paid for it: RunInstallWithObserver enforced the no-plugless-edge
rule on NEITHER of its doors while RunUpdateWithObserver enforced it on
BOTH, which is how five plugless integration edges were created across four
live deployments (corp/nc/prod, corp/bit/prod, corp/ffx/prod,
master/openobserve/default). A third path through the catalog would be a third
chance to miss a rule.
So: exactly one mutating path, and the catalog is not it. This also sharpens §7: the catalog abstracts discovery, not execution. The “higher-level abstraction on top of the primitive install” is higher-level about finding things; the install verb underneath is shared, not wrapped. It is the same argument §23 makes for one resolver with two executors, arrived at from the other end, and it is why §34.2’s compiler returns invocations instead of performing them.
38.2 What the catalog therefore owes a caller
Section titled “38.2 What the catalog therefore owes a caller”Enough to construct a VALID call against the existing API, and no more: the kind (it decides which existing verb applies), the exact version + revision selector, the required vars with their types, the required plugs, and for a vApp the parent requirement.
Covered by §34.2 (the compiler abstracts the kind), §34.4 (declare the required
plugs and the integration-satisfiable groups, satisfy nothing), and §21 (emit
repo_name + app_name + exact version+revision as separate wire fields,
never the fused token, never latest). The typed var list is the one item of
the five that Parts II/III do not name; see §37.1.
38.3 The asymmetry, in the owner’s words
Section titled “38.3 The asymmetry, in the owner’s words”“it’s always an installation or a deployment of an app, or a v deployment of a v app.” Recorded because it is the provenance of §18’s vdeployment noun, the owner used the word before the ruling that named it, in a session that had not read §18. A vApp instance is created INTO AN EXISTING PARENT DEPLOYMENT, not standalone; the regular API already has two shapes; the catalog’s job is to label the kind and name the parent requirement so the caller picks the right one. §23’s “one verb, one resolver, two executors” is the same statement in implementation terms. Not a new mutating endpoint either way.
38.4 ADDITIVE: progress feedback is needed, and there is a trap
Section titled “38.4 ADDITIVE: progress feedback is needed, and there is a trap”The owner is right that a store needs installation progress, and right that it should not be a catalog concern: reuse the existing install/deployment stream.
★ But the install progress display is SYNTHETIC. It renders hand-set
phases, while the real health observe -> rollup -> reconcile runs
out-of-band. A store that surfaces that stream surfaces something partly
theatrical. If progress is to be user-facing, the honest signal is the health
rollup, and exposing THAT over the API is a separate piece of work that must not
be smuggled in as “the catalog needs progress”.
Nothing in Parts I–III records this. It sits beside §28’s R1 rather than inside it: R1 rules that the vdeployment gate must not invent a health opinion, and a vdeployment has no health checks at all, so for the vdeployment path there is no rollup to expose, and a store showing progress for one is showing phases and nothing else. The two findings are the same lesson at two altitudes.
39. ADDITIVE: how the catalog meets the CLI, measured
Section titled “39. ADDITIVE: how the catalog meets the CLI, measured”What exists today, and it is fragmented:
| kind | how you find it today |
|---|---|
| app | shc search [query] with -c/--category, -r/--repo, -v/--verbose |
| preset | a whole family: shc preset ls / search / show / versions |
| vapp | shc search --vapp, ★ a flag that can never match anything |
| vpreset | no surface at all |
| app-level preset | none exist (§4.4, Q4, ruled yes in §19) |
★ shc search --vapp is structurally empty. It filters on app.vapp, and
zero app.yaml files in the tree declare vapp or parent_app; the
columns are scaffolded and dead, while packages ship *.vapp.yaml on disk that
the crawler never opens. So the flag ships, is documented, and returns nothing:
the same shape as a guard that guards nothing, but user-facing. §14’s second
correction and §17.3 measure the same dead columns from the data-path side; this
is what they cost at the surface.
The shape this should take. There is ONE catalog, so there is one place to
search it: shc search becomes the catalog’s read verb across every kind, with
kind as a FILTER rather than a different verb.
shc search <query>: everything the catalog carries, all kindsshc search --kind vapp|vpreset|preset|app: narrow when the caller knows- keep
--vappas an alias for--kind vapp, and make it work shc preset show/preset versionsstay: per-kind DEPTH is still useful, andshowis where §38.2’s install contract is rendered
The reason kind is a filter and not the verb: a user usually does not know whether the thing they want is an app, a vapp or a preset; resolving that is the whole value of a unified catalog. Making them choose the verb first hands the problem back to them.
★ Reconciled with §28’s R3, which reads the other way at first glance. R3
rules that shc search hides vapp template rows by default, because
browse-only rows resolve to nothing and surfacing one offers a name that cannot
be installed. “Make --vapp work” is not a repeal of R3: R3 governs the
default, --kind vapp is an explicit request. Both hold together, with
one requirement that follows from R3’s reason: when an explicit filter does
surface a vapp template row, the output must say the row is not directly
installable and name the parent it hangs off. Otherwise §39 hands the user
exactly the unusable name R3 objected to, just behind a flag.
40. ★ CONFLICT RESOLVED: the noun is application, not item and not tile
Section titled “40. ★ CONFLICT RESOLVED: the noun is application, not item and not tile”The owner’s ruling. The internal noun for what the catalog lists is
application. The UI still says “apps” to users. In the HUD (shc-x9s) the
command is :applications. Every prior draft word (item, entry,
installable, offering) is retired; rename all of them to
application.
★ This is CONFLICT (i), and the owner’s later word is the tiebreak. §34.3
records an earlier owner ruling that “the listed things are items, catalog
items”, and Parts II/III call an entry a tile in 28 places. Both lose to
application. The superseded bullet stays in §34.3 with a marker, and the
vocabulary note at the head of Part II binds the reading document-wide.
The reasoning is preserved and reused, not discarded. §34.3’s rejections
hold and are load-bearing here: app is one of the four kinds an item can be;
package is taken by the .app archive and is wrong for a vpreset entry;
entry is taken one level down by “vpreset entry”. application clears all
three. The second session’s own analysis adds the rest: item/entry say where
a thing sits, not what it is; installable, offering, listing and
deployable are verb-derived and read as provisional, and installable
additionally collides with the --installable FILTER (§37.1), where it means
“installable right now”, so one word would carry two meanings. asset is taken
in spirit (apps/frappe/compose.yaml uses it for frappe’s built static assets).
product collides with tier and entitlement language. applet was raised and
rejected FOR THE UNION because its three lineages (Java applets, desktop panel
widgets, IFTTT) all connote small and hosted inside something else, which is
wrong for Nextcloud or GitLab. It remains a good future candidate for the
vapp KIND specifically, where “runs inside a host” is the defining property
rather than a misfit.
Why tile loses on its own merits, beyond the ruling. A tile is a
rendering; it names a UI affordance. §37.3 rules the UI explicitly out of
scope, so naming the API’s central noun after a widget would embed a surface
this API does not license into the wire contract. It also cannot name the thing
before it is displayed, which is what an ingested row is.
★ This rename is OWED WORK, not a documentation edit. Measured at ce
origin/main @ 39b7f5b: modules/catalog/types.go declares type Item struct, ListResponse.Items []Item, and the comment “Item is one tile”; the
request field spells item. shc.catalog.* shipped under the retired noun
because it was built before this ruling existed.
40.1 ADDITIVE: the proximity trap, and how it is made inexpressible
Section titled “40.1 ADDITIVE: the proximity trap, and how it is made inexpressible”app and application will mean two different things three characters apart.
That was raised as an objection and the owner ruled anyway, so the risk is
accepted, but it must be structural, not a matter of care:
- the union type is
Application; it is the ONLY noun type in the catalog package - the narrow kind is expressed ONLY as a kind constant (
KindApp) and there is no type, struct or receiver namedApporAppsin the catalog package - so
Application{Kind: KindApp}is the only way to say it, and “an app” cannot be written as an identifier at all
Guard it the way this repo guards its other one-way rules: a fitness check
over the catalog package that fails on a declared identifier matching
^Apps?$, with a corpus floor so it cannot pass by scanning nothing. Two
mutations to prove it: declare type App struct{} in the package (must red) and
point the check at an empty tree (must red on the floor, not pass). The
precedent for preferring inexpressible over guarded is the mailcow length
mismatch, fixed by making the two arrays unable to diverge rather than by
validating them; the precedent for the corpus floor is this session’s
fitness-guards-that-scanned-nothing class, where a banned singleton passed every
check because the corpus was empty.
40.2 The four kinds
Section titled “40.2 The four kinds”An application is any of the four kinds, and kind is the discriminator:
| kind | what it is |
|---|---|
app | a standalone application |
preset | a named var/config bundle applied to an app (shc install <app> --preset <name>) |
vapp | an application that runs INSIDE a parent deployment |
vpreset | a curated set of vapp instances |
This is §19’s taxonomy table with the noun corrected and the catalog? column
dropped, because §20 and §35.4 own visibility. §19’s rulings that travel with
it stand: a preset never composes, it wraps exactly one installable
(preset : app :: vpreset : vapp), and --preset is typed: an app token
resolves against the app’s presets, a <parent>/<vapp> token against that
vapp’s vpresets, never across.
40.3 What to rename, measured
Section titled “40.3 What to rename, measured”- ce:
modules/catalog’sItem/Items/ theitemrequest field →Application/applications/application, under §40.1’s constraint that noApp/Appsidentifier may exist in the package. - this document: 28
tiles and theitemusages, bound by the Part II vocabulary note rather than rewritten (§44.6 explains why). Update 2026-08-05: the proseitemusages are now swept toapplication; quotes, recorded rulings and wire-spelling mentions keep the old noun as history, andtileremains bound by the note. - shc / x9s HUD:
snapshot.VappBinding(+ thevapp_bindingsJSON), the"vapp"/"vapps"row-kind strings,panels/vapp_row.go,panels/repos.go’srappitem:<repo>/<app>nav-id, and the quota axis label. The HUD refactor was deliberately scoped out of the campaign, so this is a hand-off, not a task inside it. The view is:applications. - prose and reference: the catalog API returns applications;
shc searchlists applications with aKINDcolumn;shc show <name>prints an application’s install contract and its literal command (§39).
41. ★ CONFLICT RESOLVED: ONE application table; sync INGESTS, it does not derive
Section titled “41. ★ CONFLICT RESOLVED: ONE application table; sync INGESTS, it does not derive”41.1 One table, not four, and not a computed view
Section titled “41.1 One table, not four, and not a computed view”Every repository sync ingests into a single application table. There is no
vapp table, no preset table, no vpreset table, and the existing app
table is not the place either. The owner’s reasoning: repositories synchronise
INTO a catalog, and that should not be spread across several tables.
★ This is CONFLICT (ii). §23 makes the catalog “a derived, read-only,
per-(tenant, environment) query” computed over app + preset, and §22 adds
“presets/vpresets are a third row kind, not app rows”. The owner ruled the
catalog is stored: sync ingests into one table whose rows carry an explicit
kind. The owner’s ruling wins. §22 and §23 keep their reasoning with markers
in place, because that reasoning is what was actually built and shipped, at ce
39b7f5b, modules/catalog/service.go still reads FROM app a JOIN repo r and
FROM preset p JOIN repo r.
The ruling is not merely authority; it applies this document’s own §13.3 to
the catalog. The shipped shape has an IMPLICIT discriminator twice over: app
doubles as installable-app rows AND browse-only vapp template rows behind a
vapp bool, and preset doubles as app presets AND vpreset entries behind a
wraps string beside a nullable vapp_name that has to agree with it. Both are
the same defect wearing two hats: the KIND of a row is implicit, so every
reader re-derives the taxonomy and a reader that forgets a clause silently
adjudicates a template row against real packaging. That is exactly the defect
§13.3 named on the deployment table and §18 recorded the owner ruling against.
Ruling the catalog’s discriminator explicit is that ruling applied consistently,
which is why it holds rather than merely prevails.
Consequence for the schema: fields that apply to only some kinds must be
legible, not inferred. kind is a real column with a CHECK over the four
values; parent_app + parent_vapp say what a row hangs off;
requires_parent says whether installing it needs a host; qualified stores
the one identity string every surface and the operator-suppression cascade
spells, stamped at ingest rather than recomputed per reader; two front ends
deriving it independently is §11.2’s two-front-ends test failing.
Status, measured. The ruling is built but not landed: ce
lane/application-table @ e251fa2 carries the table with migration
migrations/20260805004250_application_table.sql, and shc
lane/application-table @ 1026c3255 follows it in the hand-written DDL
mirror. Neither is on main. This document does not land them and must not be
read as having done so.
41.2 ★ D2’s browse-only semantics SURVIVE the table change
Section titled “41.2 ★ D2’s browse-only semantics SURVIVE the table change”The non-obvious half, and the one an unreconciled reading gets wrong. “One table” changes where the rows live, not what they mean. §22’s D2 stands in full:
- vapp rows remain browse-only, now as
kind='vapp'rather thanapprows behind a bool - every resolution query still excludes them: the predicate becomes
kind <> 'vapp'instead ofvapp = false - they are still stamped with the parent version they were parsed from, and the
version predicate still never applies to them (§34.5: a
.vapp.yamlcarries a FORMAT version, not a package version) - display truth from rows, install truth from archives: install always
reads the
.vapp.yamlfrom the parent’s actual archive
Which means the collisions D2 defused (four database, three plugin, three
bucket) stay structurally impossible, because nothing resolves vapp rows.
Reading the one-table ruling as a repeal of D2 would re-open exactly that
hazard. The two rulings are orthogonal: the owner ruled on storage, D2 ruled
on adjudication.
41.3 Scoped, because repositories are scoped, COVERED, and already measured
Section titled “41.3 Scoped, because repositories are scoped, COVERED, and already measured”ent/schema/repo.go carries tenant_name, environment and priority, with a
composite UNIQUE uq_repo_scope on (name, tenant_name, environment). A tenant
or even an environment can have its own repositories. So the application
table inherits that scoping, every catalog read must be scope-filtered, and
an unscoped catalog read is a defect.
Verdict: covered, and Parts II/III are stronger. §30’s rung 1 makes the
visibility filter the first rung of the resolution ladder, and §30.1 measured
the exact defect: catalogCandidates selects WHERE a.name = ? AND a.source IS NOT NULL AND a.source != '' with an optional AND r.name = ? and no
tenant_name/environment clause, while the repo table’s unique index is
(name, tenant_name, environment) and builtin sits at the sentinel
system/system scope. So one tenant’s privately-registered repo can supply an
app to a different tenant, and the ambiguity refusal can be triggered by a repo
the installing tenant cannot see. “Treat an unscoped read as a defect” is the
same rule; §30.1 is the measurement and rung 1 is the fix.
One thing the one-table ruling adds: with tenant_name/environment stamped on
the row (safe, because a repo’s scope is immutable; repo.Service.Update
accepts only priority and sync interval), tenant confinement becomes a
predicate on the row rather than a property of a join, so a reader cannot
widen past the caller’s scope by dropping a join. The measured isolation gap was
exactly one candidate query that had.
41.4 Hidden rows ARE synced. hidden is a DISPLAY flag, not a gate.
Section titled “41.4 Hidden rows ARE synced. hidden is a DISPLAY flag, not a gate.”Everything the repository carries is ingested, including hidden
applications. They are marked hidden and therefore do not display, but they
remain installable:
- sync ingests all of it; being hidden never means being absent from the table
- the catalog LISTING filters
hiddenout by default shc install <hidden thing>still works--include-hiddenreveals them in a listing when asked
Verdict: covered, and refined by §35.4. §20 already rules the derived
default with the author flag overriding both ways, and §1 already carries the
load-bearing rule that visibility never affects installability. §35.4 then goes
further than this ruling does, in the same direction: a verifier caught a
dual-meaning hidden in the shc publisher, and the key was split:
hidden: true is catalog visibility only and never affects publication or
resolution, private: true is excluded from publication entirely. The two
rulings agree; §35.4 is the sharper form and is what should be built. It also
completes the test- prefix retirement (§25.1), which is what test fixtures
were abusing visibility for.
The worry this removes: a hidden application is discoverable by an operator who
knows its name, and the only thing hidden costs is a place in the browse
list.
41.5 The .app archive is NOT the catalog row, COVERED
Section titled “41.5 The .app archive is NOT the catalog row, COVERED”The archive (.app tar) is the payload; the application row is the
index entry. The archive is copied into the deployment at install, and it is
the fallback used on a restore or when the app cannot be found at deploy time,
provided the version matches. So a catalog row must POINT at its archive.
Verdict: covered, in the same words from the other direction. §22’s D2 rules
“display truth from rows, install truth from archives”, which is this
category distinction exactly. §35.3 extends it to its limit: recover never uses
the repository or the catalog; it rebuilds from the backup’s own app package,
“the only safe way to do it”. And §41.1’s schema is where the pointer becomes
legible: source used to fuse an archive URL and a #sha256= fragment into one
string with two helpers existing only to fuse and unfuse it; it is now
archive + digest + per-version images (375 archives and digests in the
published index, with images joining them on 2026-08-04).
42. ADDITIVE: repos are PLUMBING. The catalog is the only query surface.
Section titled “42. ADDITIVE: repos are PLUMBING. The catalog is the only query surface.”The owner’s ruling: you add repos and sync them, but you do not query them. Every search (vpresets, presets, vapps, apps) goes through the one catalog, and by default you see only what is not hidden.
Verdict: ADDITIVE. Parts II/III come close from two directions and never
state it. §23 calls the repository “distribution, dumb, unchanged”; §28 rules
that repos are NOT stack-scoped (a repo is a source of things you can
install, a stack is the result of installing, and scoping a source to a result
inverts the dependency). Both are about what a repo is. Neither says a repo is
not queryable, and neither touches shc repo apps.
The test it passes: everything a repo-scoped query would give you is already a FILTER or a FIELD on the single catalog surface, so a second surface adds no capability and adds a second answer that can disagree:
| the question | answered by |
|---|---|
| what did THIS repo bring? | shc search -r <repo>; the flag already exists |
| where did this application come from? | source repo as a FIELD on the row, shown by show |
| two repos carry this name, which wins? | show listing the candidate sources, which is what makes §43.2’s adjudication legible |
| what is hidden? | shc search --include-hidden, still one surface |
Why it matters beyond tidiness. One catalog over many repos means one
ordering, one dedup rule, one answer when repos collide. The §30 ladder (the
visibility filter, the priority ranking, the version rung, and the refusal that
fires only at a same-scope, same-priority, same-version tie) is enforceable in
exactly one place. A second query surface is a second place for the old silent
ORDER BY repo_id DESC to come back.
Consequence: shc repo apps should be REMOVED. It is precisely the
duplicate “here is the stuff from the repositories” view this ruling deletes,
and it exists today (docs/reference/cli/shc_repo_apps.md). shc repo keeps
lifecycle and status only: add, sync, rm, ls (with synced_at), and
update for the priority and sync-interval knobs §29 restored.
42.1 ★ ADDITIVE: the gap this creates, and it must be closed with the ruling
Section titled “42.1 ★ ADDITIVE: the gap this creates, and it must be closed with the ruling”If the catalog is the only way to see what is available, a package that fails
to crawl is INVISIBLE. You add a repo, sync it, and your application is simply
absent: no explanation, and no verb to go look. That is the empty vs blind
failure this project keeps paying for: an empty result meaning “I could not
see” reads exactly like one meaning “there is nothing here”, and it is the same
shape as integration ls answering [] on an estate with 14 real edges, and as
backup ls answering [] with 13 snapshots present.
So this ruling is only safe if shc repo sync REPORTS WHAT IT REJECTED:
which package, which path, which parse error. Then “I do not see my app” has a
diagnosis path that needs no repo-listing verb, and the duplication stays
deleted. This is a requirement on sync’s OUTPUT, not a query surface.
★ And the crawler’s own shape makes it the only possible evidence. The crawler REPLACES a repo’s rows delete-then-insert on every crawl, so a package that stops parsing does not leave a stale row behind; it vanishes. §17.3 measured the same mechanism for a different purpose (delete-then-insert consistency holds only inside the sync’s single transactional batch, which is why lazy install-time emission of derived rows is structurally wrong). The same fact that rules out lazy emission is what makes a silent crawl rejection unrecoverable at read time. §28’s R4 bounded-parallelism ruling raises the stakes: per-app error isolation across hundreds of archives means rejections will be routine, so the report is not a diagnostic nicety.
42.2 Hidden is not unreachable, COVERED
Section titled “42.2 Hidden is not unreachable, COVERED”Hidden applications must stay installable by the PRIMITIVE install even though
the catalog will not list them by default. Consistent with §38: the catalog
being the only query surface does not make it the only install surface, and
the primitive path additionally keeps path / archive / git sources the catalog
will never carry. §41.4 is the cleanest form of this, and §35.4 is the sharpest;
hidden: never affects resolution, by ruling.
43. What presets and vapps are FOR; and the collision question is CLOSED
Section titled “43. What presets and vapps are FOR; and the collision question is CLOSED”43.1 ADDITIVE: the parent need not be an app-with-plugins
Section titled “43.1 ADDITIVE: the parent need not be an app-with-plugins”Per the owner, presets and vapps are mostly for installing things into an
application that has its own internal ecosystem: Nextcloud’s apps, Frappe’s
plugin apps. ★ But also: creating a database inside an existing database
deployment. That second use is broader than the “plugin” framing suggests and
the model must not assume the parent is always an app-with-plugins. A vapp’s
parent requirement is “an existing deployment of a named app”, and a database
engine is as valid a parent as frappe.
Parts II/III carry the data but never the constraint: §22’s D2 lists four
database vapps among its collision cases, and §18’s litmus test runs the other
way (“if it needs its own containers, network, or placement, it is an app, not a
vapp, however plugin-shaped it looks”). This ruling is the missing companion to
that litmus test: plugin-shaped is not required either. Both matter to §35.6’s
authoring contract, which is written in plugin language throughout and should
not be read as excluding the database case.
43.2 ★ CLOSED: the collision algorithm the second session left open
Section titled “43.2 ★ CLOSED: the collision algorithm the second session left open”The second session recorded the owner describing “a specific algorithm followed
to determine which repository is used when there’s a collision”, plus “you can
always select a specific repository when installing”, noted it against §19 and
Q1’s lean toward a LOUD REFUSAL, proposed the reconciliation “priority picks
a deterministic default, the chosen repo is always NAMED in the output, and
-r/--repo overrides”, and filed it “Open until the owner confirms that
reading.”
★ The owner confirmed exactly that reading, and went further. It is closed. Recorded in Part III, which that session had not read:
- §29 REVERSAL: priority is restored as the disambiguator, on the owner’s
apt argument: you type
apt install nginx, neverapt install debian/nginx; when several sources carry it, pinning priority decides; qualification is an override. And the distinction that makes it safe: what this codebase correctly killed wasORDER BY repo_id DESC, picking by insertion order, an accident deciding which packaging you get. Priority is declared operator policy, and honoring policy is not the same sin as honoring an accident. - §30 RULING C: the ladder: scope decides VISIBILITY, priority decides PRECEDENCE, they are orthogonal, and sources UNION so a tenant-scoped repo never SHADOWS the system scope.
- §36.2: the version rung: highest priority wins; among equal top priority, the highest satisfying version wins. Without that clause two repos at equal rank carrying different versions would REFUSE where apt resolves.
- §36.1 RULING E: the override is
-r/--repo, exclusively. The slash means<parent>/<vapp>and nothing else, so “select a specific repository when installing” is a flag, not a positional form. - §30 rung 5 / §36.3: the refusal survives, narrowed to where it belongs: a
same-scope, same-priority, same-version tie, after digest collapse has
removed same-artifact mirrors. So a refusal always means different bytes,
exactly when a human should look, and
X409039APPAMBmust say the tie is operator-breakable (set a priority, or qualify) rather than merely “ambiguous”.
The one requirement that is additive, and it should be built. The second
session’s phrasing demands the chosen repo be NAMED in the output, not only
when the ladder refuses (§30 rung 5 enumerates candidates) and not only when
update stickiness falls back (§31 announces a provenance change), but on an
ordinary successful pick that had more than one candidate. §21 gives the
catalog surface this for free by emitting repo_name as a separate wire field;
the CLI resolve path is where it is missing. The reason is the second session’s
own and it is right: “What must NOT happen is a pick the operator cannot see.
An ambiguity that resolves invisibly is how the wrong software gets installed
and nobody can explain why.” That is not a silent winner; it is a stated one.
44. Corrections log III: the reconciliation
Section titled “44. Corrections log III: the reconciliation”Same discipline as §14 and §24. These are claims the reconciliation itself measured false or under-stated, and the map that would have hidden them.
44.1 The map, section by section
Section titled “44.1 The map, section by section”The second session’s §16–§21 against Parts II/III. Every “covered” verdict names the section that carries it, because an unnamed “covered” is how a ruling gets dropped.
★ Left-column numbers are the second session’s OWN, now-retired numbering:
they are not this document’s sections. Its §16 became §37, §17 became §38, §18
became §39, §19 became §42, §20 became §40, and §21 was split across §41, §43
and this log. Every right-column § is live and resolves in this file.
| as filed (retired numbering) | verdict | where it lives now |
|---|---|---|
| §16 the App Store is the consumer | framing COVERED, requirements ADDITIVE | §34’s identical framing; the seven requirements land as §37.1, of which categories/tags, pagination + stable sort, entitlement-aware installability and the typed var list are new |
| §16.3 what it does NOT license | ADDITIVE | no UI/screenshots/ratings fence anywhere in Parts I–III → §37.3 |
| §17 the catalog is READ-ONLY | COVERED | §34.1’s choices/results/actions boundary; §35.2’s compile-never-execute updates; §23’s read-only |
| §17’s plugless-edge evidence | ADDITIVE | the five plugless edges across four live deployments appear nowhere in Parts I–III → §38.1 |
| §17.3 the synthetic-progress trap | ADDITIVE | nothing in Parts I–III; adjacent to §28’s R1 → §38.4 |
| §17.4 “no catalog update endpoint” | WORDING CONFLICT | read literally it deletes the shipped shc.catalog.updates (§35.2); resolved in §38: no mutating endpoint |
| §18 the CLI surface map | ADDITIVE | the fragmentation table and the structurally-empty --vapp flag → §39, reconciled against §28’s R3 |
| §19 repos are PLUMBING | ADDITIVE | §23 and §28 rule what a repo is, never that it is unqueryable → §42 |
| §19.1 the invisible-package gap | ADDITIVE | §17.3 measures delete-then-insert for a different purpose; the empty-vs-blind consequence is new → §42.1 |
| §19.2 hidden is not unreachable | COVERED | §20, §35.4, §1’s load-bearing rule |
§20 the noun is application | CONFLICT | vs §34.3’s item ruling and 28 tiles → resolved in §40, owner’s later word wins |
| §20.1 the inexpressibility guard | ADDITIVE | no equivalent in Parts I–III → §40.1 |
§21.1 one application table | CONFLICT | vs §23’s derived query and §22’s third row kind → resolved in §41.1, owner wins; §41.2 records that D2’s semantics survive |
| §21.2 scope-filtered reads | COVERED, weaker | §30 rung 1 rules it and §30.1 measured the exact unscoped query |
| §21.3 hidden rows ARE synced | COVERED, refined | §20, and §35.4’s hidden:/private: split is strictly sharper |
| §21.4 the archive is not the row | COVERED | §22’s “display truth from rows, install truth from archives”; §35.3’s repo-free recover |
| §21.5 a database engine is a valid parent | ADDITIVE | §18’s litmus test runs the other way; §22 carries the data, not the constraint → §43.1 |
| §21.6 the collision algorithm | COVERED, and CLOSED | filed OPEN pending the owner; §29 + §30 + §36.1 + §36.2 record the owner confirming that exact reading → §43.2. The “name the winner on a successful pick” half is ADDITIVE |
44.2 A literal reading of §17.4 would have deleted shipped, owner-ruled work
Section titled “44.2 A literal reading of §17.4 would have deleted shipped, owner-ruled work”“No catalog update endpoint” and shc.catalog.updates (built, on ce main,
owner-ruled in §35.2) are not in conflict: one forbids mutation, the other
compiles. Recorded because the two documents were written by sessions that could
not see each other, and a mechanical merge that trusted the newer text would
have removed a shipped endpoint on the strength of a phrase.
44.3 “Make --vapp work” and §28’s R3 look like a contradiction and are not
Section titled “44.3 “Make --vapp work” and §28’s R3 look like a contradiction and are not”R3 hides vapp template rows by default; §39 makes the explicit filter functional. Both hold, with the requirement R3’s reasoning forces: an explicitly surfaced template row must say it is not directly installable and name its parent. Without that, §39 delivers precisely the unusable name R3 refused.
44.4 “One application table” does not repeal D2
Section titled “44.4 “One application table” does not repeal D2”The loudest available misreading, and the most expensive: D2’s browse-only
rule is what makes the four database / three plugin / three bucket name
collisions structurally impossible. The owner ruled on storage; D2 ruled on
adjudication. §41.2 states the surviving predicate explicitly
(kind <> 'vapp') so no builder has to infer it.
44.5 A question filed OPEN had already been answered
Section titled “44.5 A question filed OPEN had already been answered”The collision-algorithm question (filed as “Open until the owner confirms that reading” in the retired §21.6, now §43.2) was written by a session that had not seen Part III, where the owner confirms it in §29 and extends it in §30, §36.1 and §36.2. Left unreconciled, the merged document would have carried an open question over a settled, built and tested ladder, and a builder reading it could have implemented a refusal where the ladder resolves.
44.6 The near-loss inside the “common ancestry”
Section titled “44.6 The near-loss inside the “common ancestry””§1–§15 were described as shared and were treated as safe to take from either
file. They are not identical. The shc-main variant’s §4.6 carried a passage this
file lacked: the frappe v16-on-v15 defect’s diagnosis and fix: bench get-app enforcing [tool.bench.frappe-dependencies] frappe = "<spec>" at the
ref, ten defaults naming a ref whose spec admits nothing in the shipped 15 line,
all ten re-pointed, and the guard raised to report a v16-only default as
BROKEN because as a WARNING it was indistinguishable from the twelve listed v16
pins that are refused by design, so the guard’s own first run reported all
twenty-two together and exited 0. That last clause is a guard-was-green-while-
guarding-nothing instance, the exact class this session catalogued fourteen of.
It is restored in §4.6.
44.7 The pattern
Section titled “44.7 The pattern”§14’s pattern was treating a column as evidence of a populated mechanism. §24’s was the same. This log’s pattern is “covered” asserted from a heading rather than from the text. Using the retired numbering of §44.1’s left column: the read-only ruling and the collision algorithm look covered and are; scope-filtered reads and the archive-is-not-the-row look additive and are covered; repos-are-plumbing and the database-parent constraint look covered and are not. Four of the eighteen verdicts flipped once the sentence carrying the claim was actually located, and two of those four were rulings that a heading-level merge would have dropped outright. The discipline that follows: a reconciliation must name the sentence, not the section.
45. Campaign status: what is still true, and what is stale
Section titled “45. Campaign status: what is still true, and what is stale”The campaign’s own handoff (HANDOFF-2026-08-05-catalog-campaign.md on
docs-catalog-design) is the operational companion to this document. Folded in
here so the design record does not depend on a branch, with each item measured
at shc 4ec1e105a / ce 39b7f5b.
STILL TRUE:
- The ce half landed. 70 commits (
7a81896..11b8c09): thevdeploymenttable and full rename, the one front gate, the every-resolution provenance assert, the scoped and prioritised ladder with Ruling E,shc.catalog.*(list / compile / updates), plural preset loaders, and the §25 legacy sweep. campaign/shc-adaptationmust not be pushed as-is. Independently re-measured: the branch carries 31apps/*/sso.plug.yaml, shcmaincarries 0 and 32oidc.plug.yamlinstead, and the branch is now 43 commits behindmain(it was 39 at close). Pushing it would revert thesso→oidcrename. The train verifier’s “unlicensedssoentitlement bypass / 31 broken keycloak identity edges” was measured against that stale branch and is not true ofmain; do not action it.- The shc adaptation is still owed.
go.modonmainpins cev0.0.22-0.20260804213500-7a8189698fc5, not11b8c09, so the pin bump and the adaptation have not landed. Non-tag shc pipelines resolvece@mainand IGNORE the pin (CE_TRACK=main), so ce’s landing reddens shc CI until it does. Still ONE train: the plural*.vpresets.yamlfiles cannot be read by a pre-campaign ce pin. - The
item→applicationrename on ce is owed and is now specified (§40.3). It was not in the campaign’s scope because the ruling post-dates it. - The two reversals stand, and must not be re-litigated: priority is restored (§29), and a vdeployment is deployment-SHAPED but not deployment-TABLE-stored (§18), with its own table completing that fix rather than reversing it (§26).
- Owed live proofs, none done: the follower dir-rename (leader-only checks
are not checks), terraform
wait_healthyagainst a row-only vdeployment,make test/proxmoxon the PVE host, and the three estate pre-flights before any roll: system stacks’ recorded repo isbuiltin/empty, every deployment’s recorded repo is visible in its tenant’s scope, and themax_vapp_instances/--max-vapps/shc_quota_vapp_instances_*grep across the ops repos, whose gauge rename breaks dashboards SILENTLY. - Sequencing: roll DAEMONS BEFORE publishing the re-spelled catalogue. An
app package does not ride the deb, so the catalogue is on its own clock, and a
pre-campaign daemon handed plural filenames plus
hidden:/private:keys ignores them at best. - Phase-3 condition-gated removals and the note that the recover/restore boundary normalizations are PERMANENT, not backcompat: backup archives are immutable and live forever, so a one-way migration applied when old DATA re-enters is data-migration tolerance, which the doctrine allows.
- Gotchas:
LANDING.md’s guard-provenance gates are stale (tranche-1 amendment C deliberately KEPT a narrowed synchronous check; do not “fix” it to satisfy the checklist);TestSystemAppRankingHazardis a FILE name, not a test name; the swarm-capture backup flake in./daemon/; andgo generate ./entemitting untrackedent/enttest/+ent/hook/. - Still open: Q7 (outbound LDAP as a paid boundary), the freshness guard’s
PAIR validation (§34.5), the x9s HUD refactor (§40.3), the
shc-appskill’s stale preset filenames, and the graphical catalog surface.
NOW STALE:
- “Reconcile the two catalog proposals”: DONE by this document, and the
noun is decided:
application(§40). The handoff’s step ordering that gates mergingdocs-catalog-designon the reconciliation is therefore spent. - “ce main @
11b8c09” as a HEAD: cemainhas moved to39b7f5b. The 70-commit landing is still true; the hash is no longer the tip, and the handoff’s own warning that ce moved five times during the session applies to its own numbers. - “the branch is 39 commits stale”: 43 now, and a re-derived branch exists
(
lane/shc-adaptation-rederived, 3 behindmain, 0sso.plug.yaml), which supersedes “rebasecampaign/shc-adaptation” as the instruction. - The one-table question as an open divergence: the handoff flagged “one
application table vs browse-rows + a third preset row kind” as a possible
model conflict. It is settled (§41): the owner’s table wins, D2’s semantics
survive, and it is built on
lane/application-tablein both repos. - “Nothing has landed” (§27), true of the campaign branches when written, false now for the ce half.