builtin/ vs deploy/: the placement axis is UNIVERSALITY, not dependency
Owner ruling, 2026-08-18, verbatim:
“builtin are part of every shc cluster”
“Deploy is where I deploy my custom infra stuff like license marketplace portal etc…”
★ ANSWERED SAME DAY: owner: “Both.” Both packages named “license”
move: license-broker/ gets a deployfile (deploy/license-broker.shc.yaml),
and the builtin/license app-licence socket is amputated, per the
architecture statement below. See “The answer, and what was done” at the end.
The architecture that governs licensing, verbatim (owner, 2026-08-18)
Section titled “The architecture that governs licensing, verbatim (owner, 2026-08-18)”“SHCD is supposed to handle the cluster side of license… the license management itself, it’s keygen and any custom business logic, custom APIs… is supposed to be on the portal frappe. The marketplace, the portal, those are both backed by the same frappe back end. A license is backed by the frappe back end except for the keygen part. The modules are only for traefik, Keycloak, OpenObserve, and Postgres.”
Consequences, spelled out:
- shcd owns cluster-side licence ENFORCEMENT (
modules/license: the shclic verify/refresh engine, entitlement gates). No estate APP carries licence machinery. - The portal Frappe backend owns licence MANAGEMENT (purchase records,
custody, vendor APIs, custom business logic), the same bench that backs
the marketplace and the portal (
deploy/shc/marketplace). Keygen stays its own service beside it. - The end state of
builtin/is exactly four packages:traefik,keycloak,openobserve,postgres. license leaves in this lane; branding leaves in its own concurrent lane. Anything else that wants to be a builtin re-litigates against the owner’s sentence above. - The builtin postgres is deliberately SEPARATE from the catalogue
postgres, for stability: the master-tenant system postgres is pinned to
the recorded package digest at install (
applySystemAppVersionPin) and never auto-updates when the catalogue postgres moves. One byte-shape, two roles, independent update cadences; the dual nature is the ruling, not an accident to clean up.
The rule, stated once so nobody re-litigates it
Section titled “The rule, stated once so nobody re-litigates it”| tree | what belongs there | test to apply |
|---|---|---|
builtin/<app> | packages every SHC cluster carries because the platform itself is made of them, or because any cluster may need to bind them | would a customer’s own estate ever run this? |
deploy/<stack>.shc.yaml (+ deploy/shc/<app>) | BitSpur’s own infra deployments: marketplace, portal, and the vendor-side licensing plane | is this a singleton of the vendor’s SaaS? |
The axis is not “does it have dependencies” and not “is it
proprietary”. builtin/branding stays where it is: any cluster’s gitea or
gitlab plugs into the branding socket, so it is universal even though it is
EE-only code. Vendor singletons go to deploy/, whatever they are written in.
deploy/*.shc.yaml is a glob the pipeline discovers (.gitlab-ci.yml,
“THE SET IS A GLOB, NOT A LIST”) and it is armed: SHC_DEPLOY_ENABLED is
set on this project and marketplace/production carries real deployments. A
file landed in deploy/ is a stack this repo’s CI deploys onto the vendor
estate. That is the whole meaning of the tree.
What the 2026-08-14 “System-app split” actually ruled, and why
Section titled “What the 2026-08-14 “System-app split” actually ruled, and why”docs/decisions/2026-08-14-capability-and-backlog-rulings.md, one paragraph:
The catalogue app and the system app split into distinct kinds; “pinned” means the recorded package digest. keycloak/traefik/openobserve/branding become builtin-only system apps invisible to catalogue walkers; postgres keeps its ruled dual nature (builtin AND published catalogue app). The §0.2 materialised-builtin false-red trap dies structurally.
It ruled on VISIBILITY, not on placement. The defect it closed is
HANDOFF.md §0.2: catalogue walkers keyed on whether apps/<name>/ happened to
exist after make builtin/stage, so a staged tree and a clean tree gave
different catalogue answers and a local run could go red on something not in
the repo. The fix was to make walkers key on the package’s declared kind:
(appcatalog.ScanCatalogue, catalog.CatalogueAppDirs). kind: system is a
walker instruction; it never meant “this is vendor infra”.
Today’s ruling therefore does not overturn that one; the two axes are
orthogonal. kind: says who may SEE a package; builtin/ vs deploy/ says
who RUNS it.
The one package the axis does not resolve mechanically: builtin/license
Section titled “The one package the axis does not resolve mechanically: builtin/license”builtin/license is the provider behind the third-party app-licence
socket (Windmill EE keys, Metabase tokens, plane.so registrations), not
SHC’s own entitlement licence, which is modules/license + license-broker/.
The two were deliberately kept in separate modules.
Moving it to deploy/ was proposed under this ruling. It cannot be done as
a move. Three independent structural facts, each measured against the
pinned ce (v0.0.57-0.20260818144102-30dc5d3bd507), not reasoned about:
-
The LICENSE magic token hard-resolves to
(master, default).ce/modules/app/integration_magic.go:magicProviderTenant()returnsauth.MasterRealm,MagicProviderEnvironment = "default". Measured:-i license=LICENSE→tenant="master" env="default" stack="license". -
Only a registered system app may deploy into master.
GuardMasterTenantDeployrule 1 admitsSystemAppSpecsmembership only, andapp.RegisterSystemApp("license")inmodules/applicense/register.gois the sole thing that grants it. Measured with that registration dropped:shc install license -t master=> [X403978SYSTNT] app license cannot deploy into the master tenant,master is reserved for SHC's own platform stacks-i license=LICENSE still resolves to tenant="master" env="default"=> [X404906STKNOF] stack license not found in tenant master environment defaultThe deployfile happily installs it at
(shc, prod), where no consumer can ever reach it. -
A
deploy/-sourced package is refused in master on provenance. A deployfile’sapp:is a directory path, i.e. a path source, and rule 3 refuses operator-supplied packaging in master. Measured:shc install ./deploy/shc/license -t master=> [X403979SYSSRC] platform stack license cannot be installed into themaster tenant from path, SHC's own tenant deploys SHC's own packaging
So deploy/ and “magic socket provider” are mutually exclusive addresses. A
package in deploy/ cannot be a magic provider; a magic provider cannot come
from deploy/.
The plug-ordering question, measured
Section titled “The plug-ordering question, measured”For the record, because it is the risk everyone reaches for first and it is not where the risk actually is:
-
shc install windmillwith no-i: unaffected.license.plug.yamldeclaresrequired: false. Measured:ValidateRequiredPlugsover windmill with zero integrations namespostgresand notlicense:[X400994PLGREQ] app windmill required plugs not connected, postgres. -
shc install windmill -i license=LICENSEwith no license stack: a hard, coded refusal that names the missing deployment and the command that fixes it, never a silent partial install:[X404906STKNOF] stack license not found in tenant master environment defaulthint: install the dependency first with `shc install license -t master`The daemon records that string as the stack row’s
error_messageand the row landsfailed(measured live: rows 522/533 on the workstation daemon, both removed afterwards).
That design was already correct on ordering: license was deliberately not
in shc init’s install order, and a consumer binding it early got the coded
hint. The measurement is kept because it establishes the invariant the
amputation must preserve (and does, see the end of this doc): a missing
provider is a hard coded refusal, never a silent partial install.
The answer, and what was done (same day)
Section titled “The answer, and what was done (same day)”The question below was put to the owner (the ruling’s “license” could mean two packages), and he answered “Both”, with the architecture statement at the top of this doc. Both halves are landed in this lane:
-
license-broker/→deploy/license-broker.shc.yaml. The vendor-only activation service now deploys through the same primitive as marketplace. The app package stays atlicense-broker/app(the SHC-INFRA index publish and the live estate’s repo-qualified updates read that path); the deployfile is the move that matters. Its header records the sequencing trap (do not play the gate before the corp→shc tenant move lands) and the long-term shape: brokerd’s business logic migrates onto the portal Frappe backend; only the signing seed and the shclic mint boundary stay outside Frappe, placement decided in that migration’s own lane. -
builtin/license: amputated, not moved. The measurements above are WHY it could not move; the owner’s architecture statement is why it does not survive as an app at all. Removed:builtin/license/(the nginx provider andlicense.socket.yaml),modules/applicense(the LICENSE magic token + thelicensesystem-app registration + the five mode stubs),apps/enterprise/windmill/license.plug.yaml, thelicenseentry inBUILTIN_APPS, both goreleaser payload blocks, both payload-check assertions, and the arch-fitness floor (6 → 5). BYOL is a plain consumer var:shc install windmill --var license.key=<key>; windmill’s compose already if-guarded onvars.license.key, and the amputated provider’s whole byol-var job was an emptiness check.Measured after the amputation:
-i license=LICENSEno longer crosses any tenant boundary; LICENSE parses as an ordinary unknown stack and the install refuses hard withX404906STKNOF(no silent partial install); a plainshc install windmillnames onlypostgresin its required-plugs refusal, exactly as before.Residual, stated: an estate that had bound a license edge before this lands would re-emit
-i license=LICENSEon backup recovery and refuse with the same coded error. No estate carries such an edge (the socket was days old and deliberately not in init’s install order); if one ever surfaces, the repair is to drop the edge and set the var.
Future placement decisions
Section titled “Future placement decisions”- Ask “would a customer’s estate ever run this?”: yes ⇒
builtin/(orapps/), no ⇒deploy/. - Then ask “is it a magic-socket provider?”; if yes,
deploy/is structurally unavailable to it, whatever the answer to (1). Magic providers live at(master, <stack>, default), and that address only accepts SHC-shipped packaging registered throughapp.RegisterSystemApp. - Then ask “is it licensing machinery?”; the owner’s architecture statement above already placed all of it: enforcement in shcd, management on the portal Frappe backend, Keygen beside it. No new licensing app, builtin or catalogue, without superseding that statement.