Skip to content
SHC Docs

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.yaml per add-on, typed by the presence or absence of a vapp: key. This document is left as written; the current shape is docs/app-development/addons.md.

Status: built; this note is still its only description. Q7 is answered: outbound LDAP sits behind the paid sso entitlement (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.


The discussion converged on a two-layer split, proposed by the owner:

Repository: the distribution layer. Lists apps only: the .app archives, addressed by name and version, served from GitLab packages, a git repo, or an HTTP index.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).


kindwhat it isexample
appa package with its own app.yamlnextcloud, frappe
vappa template hosted by an app, instantiable many timesnextcloud/plugin
vapp instanceone installed instance of a vappffx/erpnext
vpreset entrya curated, pinned entry in a vapp’s catalogtalk, erpnext
app preseta 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.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/prod and corp/staging can each have their own shc.
  • token is per row, so a tenant can register a private catalog.
  • priority exists and is indexed; see the open question in §12 Q1.
  • adapter is 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 → 0

Therefore:

  • plugin.vapp.yaml produces no row. The crawler never reads .vapp.yaml or .vpreset.yaml, only app.yaml.
  • The two columns are half-wired plumbing: exactly the right shape for parent/child app modelling, never connected.
  • No vapp, preset or stack schema file exists in ent/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.

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 preset appears nowhere in the file.
  • The string vapp appears 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.

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”
build-apps-archives.go
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.


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”
filescopecount in tree
apps/<name>/preset.yamlthe app itself0
apps/<name>/<vapp>.vpreset.yamlone vapp3, 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. Shipping ssoDefaultTemplate: Default made 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.0 labelled “the RESTORE rungs: the exact erpnext versions the frozen k8s benches were running.”
  • Postures. sonarqube --preset auth-off; the frappe bakeApps baked-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_id while the vapp declares appId; preset vars merge by name, so the key was dropped and the vvars default calendar won. shc install nextcloud/talk --preset talk installed the calendar app, as did every other preset, and a preset-less install.
  • frappe presets defaulted to v16 refs on a v15 core (9f4b332f7 moved them to v16, df3935c9f reverted the core, the presets were left behind), so shc install frappe/hrms would 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-app enforces [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.


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.”

kindrequired inputproposed default
appnone (has defaults)listed
vappappId! / url!hidden
app presetnonelisted
vpreset entrynonelisted

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.

  • Works at all three levels: app, vapp, and individual preset entry.
  • Hidden ≠ uninstallable. shc install <name> must still work. shc test is the standing precedent for “works, just not advertised.”
  • Orthogonal to unmaintained/acknowledged: that gates installing; this gates displaying. pos_awesome may 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 named test-something stops 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.


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:

  1. 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.vapp and app.parent_app already 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.
  2. 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.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:

kinddetected by
path. / / / ~ prefix
archive.tar .tar.gz .tgz .zip .bak .bkg .exp
gitgit+ / git@ prefix
catalog nameanything 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, never latest (§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).

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.


axismechanismstatus
catalog ↔ local rowsderived on readautomatic, cannot drift
local rows ↔ repositorysync_all_repos cron (6 h), per-repo sync_interval, manual shc repo syncsilently failed for 3 days
preset refs ↔ upstream ecosystemsnothingthe 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.


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:

layeringestsproduces
repo.adaptera foreign platform’s app store (umbrel, coolify, casaos, portainer, cloudron)SHC apps
vpreseta 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.


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.

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).


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.


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_id on those rows → the daemon expected a directory that never exists → 12 rows flipped to degraded
  • the health rollup sees 0/0 services and calls it unhealthy → shc ls can no longer express a healthy estate
  • database.orphaned-stacks now 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_name reads frappe/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_id is 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.


Claims made during the discussion and later measured false. Recorded because the reversals carry more information than the conclusions.

  1. “Presets have no icon field.” False: the documented meta schema includes icon. The three real files simply do not fill it. Not a schema gap; values to populate.

  2. “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 declare vapp or parent_app; .vapp.yaml produces no row. The columns are half-wired plumbing.

  3. “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.

  4. “Make parent_app a 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.

  5. “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).

  6. “No catalogue app needs SAML, so the socket split is hygiene.” False: apps/mautic configures itself as a SAML SP against an openid-connect client, so Keycloak refuses the AuthnRequest with “Wrong client protocol” while both provisioning jobs print success. It was a live defect.

  7. “deployment.parent_deployment_id and deployment.instance_name have 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 ce 39b7f5b / shc 4ec1e105a:

    • parent_deployment_id has three live readers, and ce main’s own quota_slash_charges_stack_axis_test.go says so in as many words (“StackModel.ParentDeploymentID itself STAYS; it still has live readers”): daemon/services_seams.go’s CountsForTenant vapp count, modules/health/reconcile’s keycloakStackEligible, and the three projections in subsystems/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_name has zero consumers, but it is still mechanically written (as NULL) and read back by modules/app/repository.go’s deployment UPSERT and selectStackCols. “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’s instance_name, not this one.
  8. “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_id is named by the self-referencing deployment_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 definition

    There is no ALTER TABLE DROP CONSTRAINT in SQLite, so the only mechanism that removes it is a table REBUILD, and deployment carries nine inbound foreign keys, eight of them ON DELETE CASCADE, which is what made the rebuild a measured data-loss event (deployment 3->1, service 1->0, host_mapping 1->0) and why migrations/catalogue_shape_test.go refuses the shape outright. The same cascade is now reproduced in-repo as a mutation probe: feeding the Atlas-generated rebuild to the real runner takes deployment 3->2, service 1->0, host_mapping 1->0, port_mapping 1->0, vdeployment 1->0.

    instance_name is the opposite case (named by no FK, no index, no CHECK) so ALTER TABLE deployment DROP COLUMN instance_name succeeds in place with foreign keys enforced and no child row moved. It went; the other stays, with its index, its To("children") edge and its three readers, until an owner ruling on how to rebuild deployment safely on rqlite. Do NOT reason from the app/preset precedent: those were droppable because they have zero inbound FKs, which is the exact property deployment lacks.

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.


  • docs/app-development/presets.md, preset format and resolution
  • docs/app-development/plugs-and-sockets.md, the socket: 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 rename
  • docs/decisions/2026-08-05-ldap-socket.md, the LDAP ruling
  • docs/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 is application and explicitly retired item and entry; 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, and item is still the wire spelling on ce main today. 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 item usages were swept to application in the gap-inventory cleanup pass (its §6 flagged that the ruling had landed while the prose had not followed). What still spells item is 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. tile is left standing per this note.

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.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 = 10 sits deliberately below DefaultPriority = 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 one Pool.Batch), so lazy install-time emission of derived rows is structurally wrong. Ruled out.
  • The parent_app/vapp plumbing 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.

kindwhat it iscatalog?
appinstallable, becomes a deploymenttile (listed by default)
presetvar-bundle around an apptile (listed)
vappthe child mechanism, becomes vdeploymentstile only when input-free (flag overrides)
vpreset entryvar-bundle around a vapp, a curated vdeploymenttile (listed)
deployment / vdeploymentthe installed resultsnever, 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 is shc 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.

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 their source fragment; 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 nginx is 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 = 50 and BuiltinPriority = 10 in ce 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 + exact version+revision (+ preset, + integration selections)) never the fused token (sidesteps the template-wins token ambiguity), never latest.

  • Rule 3 reshapes to resolved provenance: instead of refusing the RepoName spelling, 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 (CatalogAppDirResolver is 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.yaml and 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) with vapp=true, stamped with the parent version they were parsed from; every resolution query filters vapp=false; install always reads the .vapp.yaml from the parent’s actual archive. Display truth from rows, install truth from archives: collisions (four database, three plugin, three bucket) 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 application table that sync INGESTS into, with kind as an explicit column, not vapp rows carried on app behind a vapp bool 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.

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 app and preset tables. The owner ruled instead that sync ingests into an application table; 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 ce main (modules/catalog still queries FROM app a JOIN repo r and FROM preset p JOIN repo r at 39b7f5b), 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.

Claims in Part I measured false in Part II, same discipline as §14:

  1. §5.1 “both vapps”: the population is 11 .vapp.yaml files, 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.
  2. §5.1 “neither vapp is click-installable”: nextcloud/plugin is: its vplug falls back appId to the instance basename.
  3. §5.1’s “app → required input: none (has defaults)”: false for 42 of 75 apps without the integration-satisfiable exemption (§17.4).
  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.
  5. §13.2 “preset columns … every one applies”: never populated for vapp rows; and the §13 debate itself was settled the other way (§18).
  6. §7/§12 Q8 “remote-search … is already a catalog operation”: it reads no catalog data anywhere (§17.2).
  7. The backup manifest’s VAppInstanceRecord capture is dead code, not capture-without-replay: nothing populates StackContext.VAppInstances, so manifest.vapp_instances is always empty. The working path is the vapps/ 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”
  1. The test- prefix publication hack → superseded by the author flag (§5.2).
  2. repo.priority → drop (no-backcompat doctrine), or at minimum stop the schema comment implying resolution behavior it never had.
  3. shc preset search --remote + its daemon endpoint → an empty shell in production AND unauthenticated; retire when shc.catalog.* lands.
  4. The app.yaml vapp:/parent_app: keys (whole-app-as-vapp, zero users) → stop reading them in catalogManifest; the columns stay, fed by .vapp.yaml crawling. The always-empty fields threaded through the index contract and registry sidecar become redundant at the same time.
  5. Dead backup-manifest capture (VAppInstanceRecord, StackRecord.Preset*/ParentDeploymentID/InstanceName) → remove; reintroduce only as real intent-replay if that ever ships.
  6. Unreachable Python-era ports: recordStackRow’s vapp-linkage branch (stack/service.go:802-810); the IsVapp quota axis in svc.Install that no vapp install can reach → delete.
  7. Install-time materialization’s unguarded http.DefaultClient → fix with the sync-fetch work (same primitives).
  8. X403979SYSSRC as a spelling check → superseded by the provenance assert (§21).
  9. 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.

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.

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.

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.

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.

lanedelivers
install-corethe 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-provenancerule 3 from spelling refusal to resolved-provenance assert
catalog-datapathbrowse-only vapp rows, the preset/vpreset row kind, guarded archive fetch at sync, the shc.catalog.* read model, the plan compiler
legacy-sweepthe stale-prose kill list and the §25.5-6 dead-code deletions
shc-adaptationauthor 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 vdeployment schema cannot express the run half (no recorded_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/0 unhealthy was a category error rather than a bad reading.
  • R3: shc search hides 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.

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:

  1. 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.
  2. Explicit qualification wins: the -r/--repo flag restricts to that repo and stops (see §36; the slash is NOT repo qualification). An explicit operator statement outranks every heuristic below.
  3. Priority ranks the survivors, highest first, and among equal top priority, the highest satisfying version wins (§36.2).
  4. 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.
  5. Refuse only if candidates survive all of the above at the same scope and same priority. X409039APPAMB then 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 → IsVdeployment rename 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, KindDeployment and KindVdeployment in package app in 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.
  • 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.

Three namespaces, and a store composes all three:

namespaceanswersexamples
shc.catalog.*choicesbrowse, search, detail, compile, updates-available
deployment / vdeploymentresultswhat is installed, its status
install / update / uninstallactionsexecute

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).

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.

  • RULED (owner): the listed things are items, catalog items. The request field already spells it item; it stays. Considered and rejected: app (one of the four kinds an item can be), package (taken by the .app archive, 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 application and retired item and entry by 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: item is the wire spelling on ce main at 39b7f5b (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, package and entry were rejected for reasons that hold equally against them, and application is the word that clears all three objections plus this bullet’s own.

  • plan is 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 endpoint shc.catalog.compile returning installs[] of type InstallInvocation, 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.

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:

  1. Artifact version: the package’s version+revision; what the repo publishes, what the digest identifies, what pins the bytes.
  2. Preset version: which var bundle you get.
  3. 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.

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_id vs appId silently dropped the key and every install got calendar);
  • 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 latest key when it is not (nextcloud; a per-rung map would be identical vars pretending to pin);
  • name a default; fill meta, 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.

  1. 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.

needwhy it is an API concernstatus in Parts II/III
A detail read that returns the INSTALL CONTRACTA 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-classBrowsing 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 sort282 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 linksA 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 rendersEvery 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 everywhereA 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.

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: hidden is 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 old ORDER BY did. Reconciled in §43.2: §29 restored priority, §30 and §36 built the ladder, and the answer is deterministic and stated.

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:

kindhow you find it today
appshc search [query] with -c/--category, -r/--repo, -v/--verbose
preseta whole family: shc preset ls / search / show / versions
vappshc search --vapp, ★ a flag that can never match anything
vpresetno surface at all
app-level presetnone 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 kinds
  • shc search --kind vapp|vpreset|preset|app: narrow when the caller knows
  • keep --vapp as an alias for --kind vapp, and make it work
  • shc preset show / preset versions stay: per-kind DEPTH is still useful, and show is 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 named App or Apps in 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.

An application is any of the four kinds, and kind is the discriminator:

kindwhat it is
appa standalone application
preseta named var/config bundle applied to an app (shc install <app> --preset <name>)
vappan application that runs INSIDE a parent deployment
vpreseta 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.

  • ce: modules/catalog’s Item / Items / the item request field → Application / applications / application, under §40.1’s constraint that no App/Apps identifier may exist in the package.
  • this document: 28 tiles and the item usages, bound by the Part II vocabulary note rather than rewritten (§44.6 explains why). Update 2026-08-05: the prose item usages are now swept to application; quotes, recorded rulings and wire-spelling mentions keep the old noun as history, and tile remains bound by the note.
  • shc / x9s HUD: snapshot.VappBinding (+ the vapp_bindings JSON), the "vapp"/"vapps" row-kind strings, panels/vapp_row.go, panels/repos.go’s rappitem:<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 search lists applications with a KIND column; 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 than app rows behind a bool
  • every resolution query still excludes them: the predicate becomes kind <> 'vapp' instead of vapp = 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.yaml carries a FORMAT version, not a package version)
  • display truth from rows, install truth from archives: install always reads the .vapp.yaml from 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 hidden out by default
  • shc install <hidden thing> still works
  • --include-hidden reveals 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 questionanswered 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.

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, never apt 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 was ORDER 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 X409039APPAMB must 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.

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)verdictwhere it lives now
§16 the App Store is the consumerframing 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 licenseADDITIVEno UI/screenshots/ratings fence anywhere in Parts I–III → §37.3
§17 the catalog is READ-ONLYCOVERED§34.1’s choices/results/actions boundary; §35.2’s compile-never-execute updates; §23’s read-only
§17’s plugless-edge evidenceADDITIVEthe five plugless edges across four live deployments appear nowhere in Parts I–III → §38.1
§17.3 the synthetic-progress trapADDITIVEnothing in Parts I–III; adjacent to §28’s R1 → §38.4
§17.4 “no catalog update endpoint”WORDING CONFLICTread literally it deletes the shipped shc.catalog.updates (§35.2); resolved in §38: no mutating endpoint
§18 the CLI surface mapADDITIVEthe fragmentation table and the structurally-empty --vapp flag → §39, reconciled against §28’s R3
§19 repos are PLUMBINGADDITIVE§23 and §28 rule what a repo is, never that it is unqueryable → §42
§19.1 the invisible-package gapADDITIVE§17.3 measures delete-then-insert for a different purpose; the empty-vs-blind consequence is new → §42.1
§19.2 hidden is not unreachableCOVERED§20, §35.4, §1’s load-bearing rule
§20 the noun is applicationCONFLICTvs §34.3’s item ruling and 28 tiles → resolved in §40, owner’s later word wins
§20.1 the inexpressibility guardADDITIVEno equivalent in Parts I–III → §40.1
§21.1 one application tableCONFLICTvs §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 readsCOVERED, weaker§30 rung 1 rules it and §30.1 measured the exact unscoped query
§21.3 hidden rows ARE syncedCOVERED, refined§20, and §35.4’s hidden:/private: split is strictly sharper
§21.4 the archive is not the rowCOVERED§22’s “display truth from rows, install truth from archives”; §35.3’s repo-free recover
§21.5 a database engine is a valid parentADDITIVE§18’s litmus test runs the other way; §22 carries the data, not the constraint → §43.1
§21.6 the collision algorithmCOVERED, and CLOSEDfiled 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.

§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): the vdeployment table 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-adaptation must not be pushed as-is. Independently re-measured: the branch carries 31 apps/*/sso.plug.yaml, shc main carries 0 and 32 oidc.plug.yaml instead, and the branch is now 43 commits behind main (it was 39 at close). Pushing it would revert the sso → oidc rename. The train verifier’s “unlicensed sso entitlement bypass / 31 broken keycloak identity edges” was measured against that stale branch and is not true of main; do not action it.
  • The shc adaptation is still owed. go.mod on main pins ce v0.0.22-0.20260804213500-7a8189698fc5, not 11b8c09, so the pin bump and the adaptation have not landed. Non-tag shc pipelines resolve ce@main and IGNORE the pin (CE_TRACK=main), so ce’s landing reddens shc CI until it does. Still ONE train: the plural *.vpresets.yaml files cannot be read by a pre-campaign ce pin.
  • The item → application rename 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_healthy against a row-only vdeployment, make test/proxmox on the PVE host, and the three estate pre-flights before any roll: system stacks’ recorded repo is builtin/empty, every deployment’s recorded repo is visible in its tenant’s scope, and the max_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); TestSystemAppRankingHazard is a FILE name, not a test name; the swarm-capture backup flake in ./daemon/; and go generate ./ent emitting untracked ent/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-app skill’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 merging docs-catalog-design on the reconciliation is therefore spent.
  • “ce main @ 11b8c09” as a HEAD: ce main has moved to 39b7f5b. 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 behind main, 0 sso.plug.yaml), which supersedes “rebase campaign/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-table in both repos.
  • “Nothing has landed” (§27), true of the campaign branches when written, false now for the ce half.