Integration doctrine
Layer 6. Services. Services
This page states the rules. It does not restate the mechanics: the file formats, the phase pipeline and the job context live in plugs and sockets, the sub-resource model in vApps, the variable bundles in add-ons, and the runtime half in brokers. Read this page to decide what shape an integration takes; read those to build it.
Every rule below is an owner ruling. Where an older page disagreed, it has been corrected in place rather than left to be discovered.
1. The asymmetry everything derives from
Section titled “1. The asymmetry everything derives from”Two sentences, and the second is the one that does the work:
Plugs can install add-ons.
A plug may never install something on a socket.
A plug may install an add-on into its own app. Nothing installs across the boundary in either direction: the plug does not reach into the provider, and the provider does not reach into the consumer. What crosses the wire is coordinates and credentials, and nothing else.
That asymmetry is the whole model. It gives a direction test that needs no taste and no precedent:
Which side needs something installed into it? That side is the plug.
Not “which side is bigger”, not “which side is the service and which is the
client”, not “which one feels like the provider”. The install decides. An app
that must gain a plugin, an extension, a store app or a bench app before the
integration can work is the plug, and it declares <name>.plug.yaml. The
other side publishes where it is and how to authenticate, and is the
socket.
What “coordinates and credentials only” scopes. It describes what the
socket hands the plug, not what the socket does inside itself. A socket’s
integration jobs still provision the resources those credentials open: the
postgres socket creates a database and a user, the oidc socket mints a
client, the nextcloud socket writes calendar subscriptions with occ.
Provisioning inside your own deployment is exactly what integration jobs are for.
The rule forbids the socket installing into the consumer and the plug
installing into the provider.
It also does not mean a provider bakes nothing. An app builds whatever it needs into its own image in order to be a provider; that is the provider being a provider, not an install crossing an edge.
The corroborating test
Section titled “The corroborating test”The install test has a second formulation that agrees with it everywhere, and it is worth carrying because it catches the cases where “what gets installed” is momentarily unclear:
A socket is what a PROVIDER serves. The provider is the thing that already listens; the consumer plugs into it. Source: the LDAP socket decision, §12.1
Where the two tests seem to disagree, you have almost always tripped one of the three boundary cases below rather than found a real conflict.
Boundary case 1: installing is not the same as spending
Section titled “Boundary case 1: installing is not the same as spending”The ban is on installing software across the boundary. It is not a ban on the consumer using the credential it was granted.
A socket grants a capability; the consumer spends it. SonarQube writes instance-level CI/CD variables into GitLab with the token GitLab minted for it; netbird and mailcow call the Keycloak admin API with the credential the identity socket published. Neither installs anything, and both are the grant working as designed.
The condition that keeps this honest is the socket still owns teardown. The
GitLab socket makes the consumer declare ciVariableKeys precisely so the
socket can sweep exactly those keys on disconnect; the consumer cannot, since
its token is gone by then. A cross-boundary write that the socket cannot
enumerate and cannot revoke is a leak, not a grant.
Boundary case 2: a vSocket is not this boundary
Section titled “Boundary case 2: a vSocket is not this boundary”plugin.vsocket.yaml on Nextcloud, WordPress and Frappe runs
occ app:install (and its equivalents) from what is spelled as a socket job.
That is not a plug reaching across an integration edge. A vApp belongs to
its own parent (plugin.vapp.yaml declares app: nextcloud), so the whole
transaction happens inside one deployment. When nextcloud’s paperless plug
declares vapp: {name: plugin, addon: integration_paperless, mode: create}, it
is Nextcloud installing into Nextcloud, which is exactly what §1 permits.
Read *.socket.yaml as the cross-app boundary and *.vsocket.yaml as a
parent’s internal sub-resource machinery. They share a suffix and nothing else.
Boundary case 3: a provider may widen its own API
Section titled “Boundary case 3: a provider may widen its own API”When an integration needs a capability the provider does not expose, the
provider may gain one, installed by the provider, into the provider, as a
helper vApp. What it must never gain is a consumer-shaped feature. A helper
vApp exposes ONE generic capability (“create a subscription for user X pointing
at URL Y”) and never pair logic. The moment a provider carries
if consumer == "frappe", every new consumer is a change to the provider, and
the provider has stopped being substitutable.
2. The decision flowchart
Section titled “2. The decision flowchart”You are building an integration between A and B. Which is the socket, which is the plug, and where does any logic live?
flowchart TD start["Integration between A and B"] --> q1{"Does either side need something<br/>INSTALLED into it (a plugin, store app,<br/>extension, bench app) for this to work?"}
q1 -->|"exactly one side"| one["That side is the PLUG.<br/>The other is the SOCKET."] q1 -->|"neither side"| q1b{"Which side CONSUMES<br/>the capability?"} q1 -->|"both sides"| both["STOP: you have modelled it wrong.<br/>Either these are TWO integrations<br/>(split them), or one of the two<br/>installs is a bridge (§3)."]
q1b --> one2["The consumer is the PLUG.<br/>The publisher of coordinates<br/>is the SOCKET."]
one --> q2 one2 --> q2
q2{"Beyond handing over coordinates,<br/>is there LOGIC (translation, a loop,<br/>per-user or per-object work)?"} q2 -->|"no"| plain["Plain plug + socket.<br/>Socket data + plug jobs. Done."] q2 -->|"per EDGE, settled at bind"| plain q2 -->|"per USER or per OBJECT,<br/>changing after install"| bridge["It is a BRIDGE (a broker).<br/>Go to the placement ladder §3."]
bridge --> ladder["Ladder, highest rung that works:<br/>1 native plugin of the PLUG-side app<br/>2 baked into our fork<br/>3 sidecar in that app's own deployment<br/>NEVER its own top-level deployment"]
plain --> q3 ladder --> q3 q3{"Does an edge already run<br/>the other way between A and B<br/>on this SAME capability?"} q3 -->|"yes"| cyc["CYCLE: illegal. Split into two<br/>one-directional integrations on<br/>distinct sockets, or collapse into<br/>ONE bridge on one side. §5"] q3 -->|"no"| done["Ship it."]Plain-text fallback, same decision, in order:
Integration between A and B│├─ 1. Does either side need something INSTALLED into it (plugin, store app,│ extension, bench app) for this integration to work?│ ├─ exactly one side → THAT SIDE IS THE PLUG; the other is the SOCKET│ ├─ neither side → the side that CONSUMES the capability is the PLUG;│ │ the side publishing coordinates is the SOCKET│ └─ both sides → STOP. Modelled wrong. Either it is TWO│ integrations (split), or one install is a│ bridge (see 2).│├─ 2. Beyond handing over coordinates, is there LOGIC?│ ├─ none, or per-EDGE work settled at bind│ │ → plain plug + socket. Socket data + plug jobs.│ └─ per-USER / per-OBJECT work that keeps changing after install│ → it is a BRIDGE. Place it by the ladder:│ 1. a native plugin of the PLUG-side app│ 2. baked into our fork of that app│ 3. a sidecar in that app's OWN deployment│ NEVER a standalone top-level deployment│└─ 3. Does an edge already run the other way between A and B on this SAME capability? ├─ yes → CYCLE. Illegal. Split into two one-directional integrations │ on distinct sockets, or collapse into one bridge on one side. └─ no → ship it.3. Where the logic lives: the bridge-placement ladder
Section titled “3. Where the logic lives: the bridge-placement ladder”A bridge is code, not a deployment. It can technically sit on either side, but if it needs an add-on to do its job, the add-on can only be added from the plug side. That is §1 applied to the bridge itself, and it is usually what settles which side the bridge lives on.
Take the highest rung that works. Each rung down adds a process, an image, a version to track, a backup question and a failure mode.
Check rung zero first: does upstream already ship the loop? The best bridge is one you do not write. Nextcloud Mail’s provisioning middleware is the worked case: it made the whole NC↔mailcow mail integration need no bridge at all, so the integration collapsed to one admin config row written by a plug job. The embodiment ladder in brokers.md carries that rung and the detail behind each of the three below.
| Rung | What it is | The honest trade-off |
|---|---|---|
| 1. A native plugin of the plug-side app | The app’s own extension model carries the bridge: a Nextcloud store app, a WordPress plugin, a Frappe bench app. | Best case. It inherits the parent’s process, scheduler, database and backup, and it ships through a mechanism the parent already supports. Costs you the parent’s semantics: you get its hook clock, not one you chose, and you can only do what its extension API exposes. |
| 2. Baked into our fork | The app is a house soft fork, so the bridge rides the fork’s patch series or its build. | Full reach: you are inside the process, so nothing about the extension API can stop you. The cost is the fork: every rebase carries the patch, and the patch has to keep applying. Take this rung only for an app we already fork; forking an app in order to bridge it is the wrong trade. |
| 3. A sidecar in that app’s own deployment | A container in the plug-side app’s compose.yaml, sharing that deployment’s lifecycle. | Worst case, and still acceptable. You own an image and a config, but the bridge lives and dies with the app it belongs to, is backed up with it, moves with it, and never appears in shc ls as a thing an operator has to reason about separately. |
| ✗ Its own top-level deployment | Not allowed. | A bridge deployment is still a deployment: it gets a backup policy, a quota charge, an ingress question, a place in shc ls, and an independent lifecycle that can drift from both apps it joins. It also makes the pair look like three things to an operator who only ever asked for two. |
The live counter-examples
Section titled “The live counter-examples”Two pair-bridges are still their own deployments today. Both predate this ruling; neither is a pattern to copy.
| Package | Bridges | Own service |
|---|---|---|
apps/standalone/gitlab-huly | GitLab → Huly: merge requests as references on named Huly issues | gitlabhuly |
apps/standalone/huly-matrix-notifier | Huly → Matrix: notifications into each person’s DM | notifier |
apps/standalone/huly-nextcloud was the one the ruling named. It collapsed
on 2026-08-25 (SHC-244): the mirror is the hulync sidecar on
apps/flagship/huly. The other two are the same remaining debt.
The precedent: a bridge deployment already collapsed once
Section titled “The precedent: a bridge deployment already collapsed once”nextcloud-picker was a bridge deployment and was retired on 2026-08-21, along
with its two consumer plugs. apps/RETIRED:93 records why, and it is this
ruling arrived at from the other direction:
the DIRECT frappe↔nextcloud edge supersedes it:
apps/flagship/frappe/nextcloud.plug.yamlconsumes thenextcloudsocket itself, so linking a Nextcloud file into a Frappe doctype no longer needs a third app standing between the two.
The note also records the cost honestly: Huly lost the feature, because the superseding edge does not cover it. A collapse is not free, and pretending otherwise is how the next bridge deployment gets justified.
What this ruling does NOT ban
Section titled “What this ruling does NOT ban”Three shapes look like bridge deployments and are not.
- An identity-broker. A bridge converges a fact specific to one pair (“this
ERPNext user’s calendar in that Nextcloud”), so it has a side to live on. An
identity-broker converges facts keyed on the realm, with no consumer edge
at all (“every user in group X has a mailbox”): no pair, so no side.
apps/standalone/identity-broker(a hub consuming 11 plugs and servingidentityBroker) andapps/standalone/mailbox-reconcilerare that shape. - An
external-*socket shim. Ten of them, each declaringservices: {}, no container at all. They publish operator-pasted coordinates for a service outside the estate. Zero-sided, not two-sided; they join nothing to nothing. - A provider that happens to be generic.
apps/standalone/hookshotserves awebhooksocket for any producer. Serving a socket to an open set is being a provider, not bridging a pair.
The test is whether the loop has a pair. If it does, it belongs on one of the two. If it does not, it stands alone.
4. The worked examples
Section titled “4. The worked examples”Five integrations, each decided by the install test in §1.
| Integration | Plug (what gets installed) | Socket (what it provides) | Where the logic lives | Why |
|---|---|---|---|---|
| Huly → Nextcloud | huly: the bridge itself, baked into the house Huly fork | nextcloud: DAV coordinates and the huly-bridge service-account credential | Baked into our Huly fork (ladder rung 2) | The bridge tails Huly’s Redpanda queue and writes an address book plus one calendar per person into Nextcloud over DAV. Huly is a custom soft fork, so rung 2 is available; Nextcloud must stay generic or it starts switching on consumer type. Huly needs the code, so Huly is the plug. Currently mis-shaped; see §3. |
| Paperless → Nextcloud | nextcloud: paperless.plug.yaml materializes the integration_paperless store app (vapp: plugin, mode: create) | paperless: exactly three keys: hostname, port, apiUrl. No credentials, no jobs.integration, no unintegration | The Nextcloud store app, plus the plug’s own per-user url seeding | The install lands in Nextcloud, so Nextcloud is the plug even though Paperless is the “service”. The purest coordinates-only socket in the tree: it mints nothing because a paperless token is per-user, unscoped and superuser-equivalent, so each user pastes their own. It provisions nothing, so it owes no teardown. |
| Keycloak → Nextcloud | nextcloud: oidc.plug.yaml installs and configures user_oidc through occ in a plug job; no vapp: key | oidc: issuer, client id, client secret, redirect URIs | The user_oidc store app plus the plug’s own jobs | Nextcloud is the side that needs software installed, so Nextcloud is the plug. user_oidc is invisible plumbing whose whole configuration is the credential, so a plug job installs it directly rather than declaring a visible vApp instance. |
| Keycloak → WordPress | wordpress: oidc.plug.yaml materializes the daggerhart-openid-connect-generic plugin (vapp: plugin, mode: create) | oidc: the same substitutable contract | The WordPress plugin; the plug job only soft-gates and configures | Identical shape to the row above with a different extension model. Same socket, two different plug-side mechanisms, which is exactly what a capability socket is for. |
| Frappe → Nextcloud | frappe: nextcloud.plug.yaml registers and activates the baked frappe_nextcloud bench app; no vapp: key, by ruling | nextcloud: ocsUrl, the observation grant, and the per-user subscription write | The baked bench app (image-owned), plus the provider’s own occ job | Frappe needs the bench app, so Frappe is the plug. Nextcloud gains no software at all: the occ dav:create-subscription write happens inside Nextcloud only because dav:* is CLI in that container and CalDAV authorises per principal. That is the socket provisioning inside itself, not the plug reaching across. |
★ The pattern: Nextcloud is both
Section titled “★ The pattern: Nextcloud is both”Four of those five rows have Nextcloud on one side. It is the socket in two of them (Huly, Frappe) and the plug in the other two (Paperless, Keycloak). That is not an inconsistency. It is the model working:
Nextcloud is a SOCKET when something consumes its storage, and a PLUG when it consumes something else.
The same app takes both roles, decided per integration by the install test,
never once, globally, by what kind of app it is. The tree measures it:
apps/flagship/nextcloud/ ships three sockets (nextcloud,
nextcloudWebhooks, webdav) and eight plugs (imap, llm, mysql,
oidc, paperless, postgres, s3, smtp). Frappe, GitLab, Matrix, Huly,
Mailcow and Paperless all have the same dual shape.
So “is Nextcloud a provider or a consumer?” is a malformed question. Ask instead: for this capability, which side has to gain software?
Two plug-side install mechanisms, and which to use
Section titled “Two plug-side install mechanisms, and which to use”Both mechanisms are the plug installing into its own app; they differ in whether the operator should see the result.
- A plug job that installs the store app directly: nextcloud’s
user_oidcandintegration_openai. Use it when the app is the pure mechanism of the edge: invisible plumbing whose entire configuration is the credential the edge carries, and which an operator would never pick off a listing. - A declared
vapp:entry: nextcloud’smailandintegration_paperless, wordpress’s two plugins. Use it when the result is user-facing functionality: it becomes a visible, quota-charged instance inshc ls, and it is retained on detach.
The dividing line is stated once and holds: a plug never installs a top-level app.
5. No cycles
Section titled “5. No cycles”Never have cycles. A → B → A is illegal.
An integration is a directed edge: plug → socket. A cycle is two edges on the same capability running opposite ways between the same pair, and it is always a modelling error, because it means each side needs something installed into it for one integration, which §1 forbids and §2 sends you back from.
The rule is over DECLARED plug/socket edges: the *.plug.yaml files that
exist on disk. It is not about which direction bytes travel at runtime. One
declared edge routinely carries values both ways: SonarQube plugs GitLab,
GitLab mints a token for it, and SonarQube then writes CI variables back into
GitLab with that token. That is one edge, not two, and GitLab declares no
sonarqube plug. Not a cycle. Count files, not data flows.
What to do instead
Section titled “What to do instead”Two legal shapes, and they are not interchangeable:
- Split into two one-directional integrations, when the two directions are genuinely different capabilities. Each gets its own socket stem, its own plug, and an explicit install order. This is legal precisely because they resolve at different times.
- Collapse into one bridge on one side, when the two directions are one capability that happens to move data both ways. Pick the side by §1, place it by §3, and the “other direction” becomes an internal detail of the bridge rather than a second edge.
The in-tree reference for shape 1 is ivatar ↔ Keycloak:
ivatar --(oidc.plug)--------> keycloak ivatar gets its own loginkeycloak --(libravatar.plug)--> ivatar keycloak gets the avatar base URLTwo distinct sockets (oidc, libravatar), two distinct capabilities, one
stated order: install Keycloak, install ivatar with -i oidc=<keycloak>, then
integrate the realm with -i libravatar=<ivatar>. Both plugs are live:
apps/flagship/ivatar/oidc.plug.yaml and apps/keycloak/libravatar.plug.yaml.
Reasoning in
the avatars decision.
How a reviewer detects one
Section titled “How a reviewer detects one”There is no lint for this today. Check it by hand, in this order:
- Draw one arrow per edge, plug → socket, labelled with the socket stem. Do it per stem, not per app pair: the stem is the capability, and the capability is what may not loop.
- Same stem, both directions, same pair → cycle. Refuse it. This is the unambiguous case and needs no judgement.
- Different stems, opposite directions → not a cycle, but prove the
bootstrap. Ask whether an operator can install the pair from nothing. If
both plugs are
required: true, neither app can be installed first and the pair is unbootstrappable, which is a cycle in practice even though the stems differ. The ivatar pair passes becauseoidc.plug.yamlisrequired: false; the avatar edge is a later, additive step. - Follow chains, not just pairs. A → B → C → A is the same illegality with more hops. In review, the tell is a new plug on an app that something in the chain already plugs into.
6. Frappe: baked in, or an add-on
Section titled “6. Frappe: baked in, or an add-on”Frappe is the one parent in the catalog that supports both install paths: a
bench app can be baked into the image, or delivered as a vApp add-on
against frappe/plugin. Two paths means a decision, and the decision is ruled.
The rule
Section titled “The rule”A Frappe app that is part of an integration is baked in only.
If it would be used in both ways, baked in wins: one path, not two.
If it is not part of an integration, support both.
Because the integration has to work in the baked scenario, and only the baked path is available there. Two mechanics force it:
- A live gunicorn cannot import a runtime-added Python app. A bench app dropped into a running Frappe is not loadable until the process restarts, so a runtime install is not a mechanism an integration can depend on completing. Frappe also has no upstream marketplace to install from, so there is no third option.
- The bench volume is seeded once. In the default non-baked mode the volume is seeded on first install; on an existing deployment the seed marker already exists and a newly baked app does not arrive, with no error. An integration whose mechanism can silently fail to be present is not wired, it is hoping.
So a plug’s mechanism extension on Frappe is image-owned: baked by
frappe/docker/Dockerfile and activated through vars (activateApps, or the
plug’s own job), never declared as a vapp: dependency. The catalog is
consistent with this: all six Frappe plug files (imap, keycloakAdmin,
mysql, nextcloud, oidc, smtp) declare no vapp: key, and
apps/flagship/frappe/nextcloud.plug.yaml says so at the site rather than
leaving the absence to look like an oversight. The negative is pinned by
apps/flagship/frappe/tests/tests.bats. frappe/plugin vdeployments remain
the path for user-facing apps, which is exactly the set no plug needs.
frappe_medusa is the clean shape to copy: a plug mechanism, baked, activated
purely through activateApps, with no add-on file and no vApp.
What “baked wins” already does mechanically. Where an app is both baked and
published as an add-on, the vApp path adopts the baked copy rather than
fighting it: plugin.vsocket.yaml prints
install-plugin: <app> is present in apps/, adopting (no clone, no pip install),
and a test asserts get-app never runs. So the collision degrades safely. It
is still two paths, and the rule is that a plug mechanism must not have two.
Two apps are in that state today, erpnext and frappe_keycloak, each baked
into the image and also shipping an addons/*.addon.yaml. frappe_keycloak is
the one that matters: it is the OIDC plug’s mechanism, so under this rule its
add-on file is the second path that should go. That is a catalog change, not a
doc change, and it is owed.
The single-path half of the rule is the same argument from the other end. If an app is reachable two ways, some estates get it baked and some get it as an instance, and every failure report starts with “which one do you have?” One path, and the path is the one that always works.
The test a developer applies
Section titled “The test a developer applies”Three questions, in order, first yes wins:
- Is this bench app the mechanism of a plug? Does an integration stop
working without it? → Bake it. No
vapp:key, no add-on file. - Would it be useful both inside an integration and on its own? → Bake it. Baked wins; do not also publish it as an add-on.
- Neither: it is user-facing functionality an operator picks by name? → Support both. Publish the add-on, and bake it where the image should carry it.
The mirror-image rule for store-app parents. Nextcloud and WordPress have no
bake model: their plugins are runtime volume content, PHP has no preload
window, and occ app:install / the WP CLI are reliable, so those parents keep
using vapp: for the surfaces their edges land on. The rule is per parent, and
it follows the parent’s delivery physics, not a preference.
7. vApp mechanics
Section titled “7. vApp mechanics”The vapp: modes actually in the catalog
Section titled “The vapp: modes actually in the catalog”A plug’s vapp: key declares the vApp instances the edge lands on. There are
exactly two modes, and the tree uses one of them:
| Mode | Meaning | In the catalog |
|---|---|---|
require | The default. The edge expects the instance to already exist. The plug’s jobs gate on it and print the shc install <app>/<vapp> command when it is absent. | 0 declarations. It is what you get by omitting mode:, which is why a plug that means create must say so. |
create | The engine materializes the instance after the consumer deploys, through the real vdeployment path: visible in shc ls, quota-charged, and retained on detach. | 4 declarations, listed below. |
Every vapp: block in the tree, measured:
| Plug file | vApp | Add-on | Instance | Mode |
|---|---|---|---|---|
apps/flagship/nextcloud/imap.plug.yaml | plugin | mail | mail | create |
apps/flagship/nextcloud/paperless.plug.yaml | plugin | integration_paperless | integration_paperless | create |
apps/integrated/wordpress/oidc.plug.yaml | plugin | daggerhart-openid-connect-generic | (same) | create |
apps/integrated/wordpress/smtp.plug.yaml | plugin | wp-mail-smtp | (same) | create |
Four blocks, all mode: create, all against a plugin vApp, all on store-app
parents. Frappe declares none, by §6.
Two things the count is worth reading for. create is the common mode because
a plug that materializes its own mechanism is the normal case, and require
would push a manual step onto every operator. And mode: is not optional in
practice: omitting it silently means require, which turns a
materialize-my-mechanism plug into one that refuses until somebody installs the
instance by hand.
vApp vs add-on vs deployment
Section titled “vApp vs add-on vs deployment”Three nouns that all end up as something installed, and they are routinely confused.
| vApp instance | Add-on | Deployment | |
|---|---|---|---|
| What it is | a sub-resource inside a parent deployment: a realm, a database, a bucket, a plugin instance | a versioned variable bundle, one <name>.addon.yaml file: a named configuration, not a thing that runs | a full deployment: the ordinary unit shc install <app> produces |
| Runs containers? | No. Rows in the database plus jobs against services the parent already runs | No. It is a file; it configures whatever it is applied to | Yes. Its own compose services |
| Addressed as | <stack>/<instance> (--into and --instance) | <app>/<name>[@<version>] | the stack name (-s) |
| Owns | per-instance vars and credentials | version keys and var overlays | compose, networks, volumes, backup policy, ingress, quota |
| Lifecycle | uninstalled with the parent, or by name | none of its own | independent |
The relationship: an add-on that declares vapp: <name> is how you name
the configuration for a vApp instance of that vApp; an add-on with no
vapp: key configures the app itself and installs as a plain
deployment. So shc install nextcloud/talk reads the add-on file, learns
it belongs to the plugin vApp, and materializes a talk instance under the
nextcloud deployment. One token, three concepts, and the file on disk is what
decides which.
Against a deployment, a vApp instance is the cheap one: no compose, no networks, no volumes, no ingress question. That is the reason to prefer it whenever the thing is genuinely owned by a parent. Against an add-on, a vApp instance is the thing that exists at runtime; the add-on is only the recipe.
8. Tier 1 and tier 2: an open question, not a taxonomy
Section titled “8. Tier 1 and tier 2: an open question, not a taxonomy”Finding: the corpus does NOT define a tier-1 / tier-2 taxonomy of integrations. Two documented usages of the word “tier” sit near the integration model, they mean different things, and neither one splits integrations into tiers. Recording that plainly is worth more than manufacturing a definition.
What the corpus actually says.
-
“tier-1 substitutability” in
plugs-and-sockets.md:180: “That breaks tier-1 substitutability, which is the whole promise of a capability socket.” Here “tier-1” modifies substitutability and means first-class: substitutability is the socket’s primary promise, and the outcome-namedssostem broke it. It is a one-off intensifier. It does not name a tier of anything, and no “tier-2 substitutability” exists anywhere. -
“tier-2 validation” in
plugs-and-sockets.md:723: “Discovery is tier-2 validation of the connection.” This one is part of a real, defined taxonomy, but the taxonomy is of validation, not of integrations. It is defined indocs/superpowers/specs/2026-07-13-connections-namespace-design.md:395-441as four tiers keyed on when a failure becomes knowable:Tier When What it catches 0 connection-create, once the root credential probed against the live provider before anything is stored 1 install-time: structural, local, cheap required vars, required plug, valid type, grant exists, templates resolve 2 deploy-time: semantic, remote, in the jobs.discoveryprobeis the endpoint reachable, does the credential actually authenticate 3 runtime token expiry, revoked roles, outages: observability, not validation
So the two usages are unrelated, and neither is about integration kinds.
On the working reading that prompted this. The proposed reading was “Tier 1 = a substitutable capability socket; Tier 2 = a named point-to-point integration between two specific apps.” That reading is not supported:
- Tier 1 in the only defined ladder is install-time structural validation, not a class of socket.
- Tier 2 there is the discovery probe. It is not a kind of integration, and it
applies to every socket including the most substitutable ones:
postgresands3are the ladder’s own cited examples (check-postgres-ready,check-s3-ready).
The distinction the reading is reaching for does exist, under a different
name. plugs-and-sockets.md defines exactly two classes of socket, and calls
them neither tier 1 nor tier 2:
- Capability sockets: named for the wire protocol, substitutable by
construction, and an
external-<name>shim is nameable.postgres,mysql,s3,smtp,imap,oidc,saml,ipfs,libravatar,llm. - Singleton sockets: named for the app, because the app is the
capability and there is no second speaker. 25 of them, including
nextcloud,paperless,mailcow,immich,metabase.
That split is real, load-bearing, and already has the two-question test that picks between them. It is almost certainly the thing “tier 1 / tier 2” was gesturing at.
Open question for the owner. Should the capability/singleton split be renamed tier 1 / tier 2, or should the word “tier” stay reserved for the validation ladder? Doing both invites the collision this section had to untangle. Until it is ruled, say “capability socket” and “singleton socket” for the socket classes, and reserve “tier N” for validation timing.
9. Smells: signs you have modelled it wrong
Section titled “9. Smells: signs you have modelled it wrong”Each of these is a shape that parses, deploys and looks green.
- A bridge as its own deployment. If an app exists only to join two other
apps, and it is not a realm-keyed identity-broker, it is on the wrong
rung. Walk §3 upward: can it be a plugin of the plug-side app? Baked into a
fork we already carry? A sidecar in that app’s deployment? The tell in review is
an
app.yamlwhose description is “X to Y” and whose plugs are exactly X and Y. - An add-on named on the socket side. A socket file that names a plugin,
store app or bench app has crossed the boundary: it is describing an install
it does not own. The install belongs to the plug, in that app’s own
<name>.plug.yaml. If the socket seems to need it, you have the direction backwards: re-run the install test in §1. - A cycle. Same socket stem pointing both ways between one pair. Also its
quieter form: two different stems both marked
required: true, so neither app can be installed first. See §5. - A Frappe app with two install paths inside an integration. A bench app
that is both baked and published as an add-on, where a plug depends on it.
Pick baked; delete the add-on file. Two paths means every bug report starts
with a question. Live instance:
frappe_keycloakis baked and shipsaddons/frappe_keycloak.addon.yamlwhile being the OIDC plug’s mechanism. See §6. - A socket that mints something the plug should own. A per-user token, an
unscoped superuser credential, or anything the socket cannot revoke per
consumer.
paperless.socket.yamlis the worked refusal: it mints no API token at all, because every token it could mint would be superuser-equivalent and shared. Publishing the URL half and letting each user paste their own is the correct, smaller answer. - A socket that switches on consumer. Any
if consumer == "<app>"inside a provider, or a socket field only one named consumer reads. The provider grants one generic capability; pair logic lives on the pair’s side. - A plug that installs a top-level app. A plug job running
shc install <something>. A plug materializes vApp instances and its own mechanism; it never creates deployments.
Related
Section titled “Related”- Plugs and sockets: the mechanics: file formats,
socket naming, integration phases, the
vapp:key - Brokers: the runtime half, the embodiment ladder, and where a master credential may live
- vApps: the sub-resource model and the closed document key set
- Add-ons: the
<name>.addon.yamlcontract and catalogue freshness - Bundled services: when not to reach for a plug
- Splitting
ssointooidcandsaml: why an outcome-named socket breaks substitutability - The
ldapsocket and SSO socket credential scope - The GitLab provider socket
docs/proposals/2026-07-25-app-bundling-vs-sockets-audit.md: the audit that established the bundling rule; not published to the site