Skip to content
SHC Docs

The commerce edge: ERPNext serves, Medusa consumes

Archived, superseded by Frappe is the platform and Medusa is not adopted as infrastructure.

The commerce edge: ERPNext serves, Medusa consumes

Section titled “The commerce edge: ERPNext serves, Medusa consumes”

★ RE-SCOPED BY OWNER RULING 2026-08-16: READ THIS FIRST

Section titled “★ RE-SCOPED BY OWNER RULING 2026-08-16: READ THIS FIRST”

The owed work in §5 and §7 of this document is NO LONGER OURS.

docs/decisions/2026-08-16-frappe-over-medusa.md rules that Frappe/ERPNext is the platform for everything and that Medusa is not adopted as infrastructure, not for DesiBox, the SHC portal, the marketplace, BitSpur or FlyingFoxLabs. The Medusa↔ERPNext bridge therefore leaves our backlog and becomes a customer-funded feature.

What that ruling does not do: it does not deprecate apps/standalone/medusa. That package remains a catalogue app we sell, edge and all. The ruling governs what we run, not what we ship.

§5 is superseded twice over. Once by reality: the sidecar rung was abandoned for compiled-in Medusa Subscribers (push) plus the provider-side frappe_medusa bench app (pull); the canonical account of that move is in apps/standalone/medusa/erpnext.plug.yaml and compose.yaml. And once by the ruling, which reassigns who pays for whatever remains. Read §5 as a historical contract, not as a task list. The paths in the table below are also pre-reorganisation: the consumer now lives at apps/standalone/medusa/ and the provider at apps/flagship/frappe/.

Everything else here (§0’s measured facts, §1’s direction argument, §3’s mint/revoke design, §4’s auth model) still stands and is still the reason the shipped edge is shaped the way it is.

Status: design document + landed phase 1. Written 2026-08-09 alongside the code it describes:

filehalf
apps/platform/frappe/erpnext.socket.yamlprovider: the erpnext singleton socket, its bench gate, its mint and its revoke
apps/business/medusa/erpnext.plug.yamlconsumer: the bind, the narrow attach, the embodiment argument
apps/business/medusa/medusa-erpnext-arm.job.yamlconsumer: the proof and the vault seal
apps/business/medusa/compose.yamlconsumer: the (double-gated) sync sidecar
apps/business/medusa/{vars,app}.yamlconsumer: the knobs and their types
apps/business/medusa/tests/tests.bats17 static guards

The question it answers: how does a shop stop being a second copy of the business?


0. Ground truth: measured facts this design leans on

Section titled “0. Ground truth: measured facts this design leans on”

Everything in this section was read out of source or measured, not recalled. Anything not in this section that reads like a fact is a claim.

G1. Medusa v2 has no outbound webhooks and no runtime plugin loading. The supported extension point is a Subscriber under src/subscribers/*.ts, compiled into the application by medusa build; plugins are build-time node modules. Already recorded in apps/business/medusa/vars.yaml’s images.medusa note, which is also why this app ships its own image and its own Dockerfile.

G2. Frappe is multi-tenant BY HOST HEADER, and there is no default_site fallback in the WSGI path. frappe/app.py:183 (version-15):

site = _site or request.headers.get("X-Frappe-Site-Name") or get_site_name(request.host)
frappe.init(site=site, sites_path=_sites_path, force=True)
if not (frappe.local.conf and frappe.local.conf.db_name):
# site does not exist
raise NotFound

apps/platform/frappe/compose.yaml records this as measured on this estate (2026-08-04, hq.corp.bitspur.com against site hq.bitspur.com) and names X-Frappe-Site-Name as one of the two mechanisms proven to work. This is the single most load-bearing fact in the whole edge. An overlay alias is never a site name, so a consumer dialling internalUrl without that header gets a bare 404 for every request, including a perfectly authenticated one, and a 404 reads as a wrong path, so it gets debugged as a wrong path.

G3. Frappe’s API-key pair is readable back after creation. frappe/auth.py:700-720, validate_api_key_secret, is frappe’s own authenticator and it reads the stored secret on every request:

doc_secret = get_decrypted_password(doctype, docname, fieldname="api_secret", raise_exception=False)
if doc_secret and api_secret == doc_secret:

It also filters the user on {"api_key": api_key, "enabled": True} (:708), which is what makes “disable the user” a complete revocation.

G4. The auth header is Authorization: token <api_key>:<api_secret>. frappe/auth.py:683-690: auth_type.lower() == "token" splits on :; "basic" base64-decodes the same pair. A malformed pair is swallowed (except (AttributeError, TypeError, ValueError): pass, :693) and the request continues as Guest, so “authenticated as Guest” is a distinct, detectable failure and the arm probe checks for it by name.

G5. frappe.core.doctype.user.user.generate_keys is a ROTATOR. user.py:1326-1342: it assigns a fresh api_secret unconditionally (:1339) while preserving api_key, and carries frappe.only_for("System Manager") (:1332). Calling it on every deploy rotates the credential on every deploy.

G6. User.add_roles / remove_roles call self.save() themselves (user.py:617, :625). append_roles (:608) does not. And user_type is DERIVED, not set: set_system_user (:307) resolves it to "System User" if self.has_desk_access() else "Website User". A role set with no desk access silently produces a Website User whose ERPNext reads all 403.

G7. ERPNext role names, read out of erpnext version-15 doctype JSON.

DocTyperoles present
ItemAccounts User, Desk User, Item Manager, Maintenance User, Manufacturing User, Purchase User, Sales User, Stock Manager, Stock User
BinPurchase Manager, Purchase User, Sales Manager, Sales User, Stock Manager, Stock User
Sales OrderAccounts User, Maintenance User, Sales Manager, Sales User, Stock User
Item PricePurchase Master Manager, Sales Master Manager, and nothing else

The last row is the sharp one: ERPNext offers no read-only role over pricing in version-15, so “let Medusa read prices” and “let Medusa rewrite your price lists” are the same grant.

G8. bench --site <site> list-apps reports the apps installed ON THE SITE. frappe/commands/site.py:534 reads the Installed Applications single and falls back to frappe.get_installed_apps(); :522-526 pads the name column to the widest app name. That is the right question: an app present in apps/ but never install-app-ed on the site has no doctypes there.

G9. A minted value reaches the consumer’s post-hook render and NOTHING ELSE. ce modules/app/install_runner.go: the compose file is rendered at ~:860-930 from integrationsCtx; RunSocketIntegrationJobs runs at :1461; MergeJobMintedValues(integrationsCtx, …) at :1473. The compose render is ~600 lines and one whole phase earlier. This is the constraint that put sonarqube’s GitLab binding and gitlab’s Sentry seal in their apps’ hooks, and it puts ours there too.

G10. The hook seal is MINT-ONCE. ce modules/app/hook_actions_run.go defines two channels: ::shc-hook:var: (plaintext, lands verbatim in vars.yaml + manifest var_overrides) and ::shc-hook:secret: (routed through the vault, only a ref+vault://…?autogen persisted). hook_minted_vars.go’s sealHookSecret is documented “Idempotent (mint-once): a re-install reuses the value sealed by the first”, and a failed seal fails closed; it is never downgraded to a plaintext write.

G11. No sync image exists. Searched 2026-08-09:

  • github.com/aerele/medusa_integration: real (MIT, 31 stars, last push 2026-07-30), and not this. It is a Frappe bench app, i.e. it runs on the provider side; its Medusa Configuration doctype stores admin_email + admin_password and exchanges them for a Bearer token, i.e. ERPNext holds a Medusa administrator’s password; and it is not a general connector; the repo adds ~25 bespoke storefront DocTypes (Homepage Banner, Best Deals, Email OTP, Medusa Wishlist, Product Details Banner, Product Collection…) and customises ~20 core ERPNext doctypes (Item, Sales Order, Sales Invoice, Quotation, Customer, Lead…). That is one integrator’s client build, not a mechanism. Evaluated and rejected.
  • gitlab.com/bitspur/community/medusa-erpnext-sync appears in web-search results and does not resolve: the unauthenticated GitLab API answers 404 Project Not Found. The on-box token at ~/.tokens/gitlab returns 401, so a private-project check could not be completed; see §7. It is treated as non-existent and nothing pins it.

1. Direction: ERPNext serves, Medusa consumes

Section titled “1. Direction: ERPNext serves, Medusa consumes”

The test is not which app matters more. It is which side holds the record the other is a projection of.

Items, stock, prices, customers, receivables and the general ledger exist whether or not a shop does. ERPNext is the book. A Medusa product is a merchandising view of an ERPNext Item: it carries storefront-only facts (handle, collection membership, SEO copy, the variant option matrix) that ERPNext has no opinion about, and it is reconstructible from the Item if lost. An ERPNext Item is not reconstructible from a Medusa product; losing it loses valuation, the purchase history, the tax template and the ledger lineage.

The direction also falls out of the socket rules mechanically, which is the stronger argument because it does not depend on taste:

A provider is the side that can mint a per-consumer, scoped, revocable credential.

ERPNext can: a Frappe User with an API-key pair is a first-class identity with roles, an enabled flag, and an audit trail (G3, G7). Medusa v2 cannot; its admin identity is an email/password row in the user table, there are no API tokens, no service accounts and no per-integration roles. An edge pointing the other way would have to hand ERPNext a shared Medusa administrator password, which is exactly what the one existing open-source connector does (G11) and exactly why this design does not use it.

Naming. erpnext, the bare app name, because this is a tier-2 app-dialect contract: the wire is Frappe’s REST dialect and the payload is ERPNext’s record model. Not erp, an outcome name with a dozen unrelated faces (Odoo, Dolibarr, Tryton, NetSuite) and nothing a consumer could write against. Not frappe: that is the framework, and a bare Frappe bench has none of Item, Bin, Sales Order, Sales Invoice, Payment Entry. A future framework-level socket (Users, Files, the OAuth server) would take the frappe stem and would be a different, narrower thing.


2. Embodiment: a compose sidecar, consumer-side

Section titled “2. Embodiment: a compose sidecar, consumer-side”

The ladder is native loop > plugin vApp > fork-carried > compose sidecar. Each rung above the sidecar is unavailable or refused, for a reason that belongs to the software rather than to taste:

Native loop: unavailable. Medusa has no outbound webhooks and no way to register an external listener at runtime (G1). There is no configuration that makes a stock image sync anything.

Plugin vApp: unavailable. Medusa’s plugins are build-time node modules resolved by medusa build (G1). There is nothing for a vApp to install into a running Medusa; “installing” one means rebuilding the image, which is not what a vdeployment does. (Contrast frappe and wordpress, whose app/plugin models genuinely admit runtime addition, and note that even on frappe the house ruling is that plug mechanisms are image-owned, baked and vars-activated, never vapp:.)

Fork-carried: available, and deliberately refused. This app’s image is ours, built from the Dockerfile in its own directory, so compiling the sync in as a Subscriber is genuinely on the table and is the rung the ladder would otherwise pick. It is refused on coupling:

  • the sync would ship on Medusa’s clock; every sync bugfix becomes a Medusa image rebuild and a full-stack redeploy;
  • a sync crash-loop becomes a crash-loop of the process serving checkout;
  • most of the work has no event to subscribe to. Catalogue and stock are a pull on a timer; only the order push is event-shaped.

A rung is not worth taking when it buys nothing the rung below lacks and costs the blast radius of the checkout path.

Compose sidecar: taken. The bridge is its own container in Medusa’s stack, on Medusa’s own clock, restartable and diagnosable alone. The bridge is the broker, this is an edge broker, and per house doctrine edge-brokers run consumer-side. Identity-brokers would be provider-adjacent; this is not one.

The order push lives in the sidecar too, even though that half is event-shaped, because splitting the halves across two runtimes (a compiled-in Subscriber pushing, a sidecar pulling) would put one edge’s state in two places on two release clocks. The sidecar polls Medusa’s Admin API for orders. The cost, stated plainly: push latency is one poll interval, not sub-second. For an order landing in an ERP that is correct; for a payment-capture webhook it would not be, and payment capture is not in scope.


frappe the app and erpnext the bench app are on separate clocks. The image pin can carry erpnext (today’s does), a factory core flavour does not, and in VAPP mode, the default, the bench volume is seeded ONCE and an image bump is a documented silent no-op for apps/ (vars.yaml’s images.frappe note). So “the frappe stack is up” says nothing about whether the doctypes this socket’s entire contract is made of exist.

Without the gate the failure is invisible in the worst way: the bind succeeds, the mint succeeds, the consumer authenticates successfully, and then every /api/resource/Item answers 404, which reads as a wrong path, not a missing app.

The job therefore:

  1. resolves the site: vars.siteName when it exists on disk, else the bench’s only site, else refuses. (The fallback is not paranoia: both live production benches are restored ones, and a restored site keeps its archive’s name while vars.siteName goes on naming whatever the install was given.)
  2. runs bench --site <site> list-apps and requires an anchored ^erpnext (G8);
  3. on failure, prints the apps that are installed and the per-mode fix: activateApps=erpnext when erpnext is on the bench but not on the site; an erpnext-carrying image when bakeApps=true; and for bakeApps=false the explicit warning that an image bump will NOT change apps/.

One dedicated Frappe User per consumer: shc-<label>@integration.invalid. .invalid is RFC 2606 reserved, so the account can never send or receive mail; send_welcome_email = 0 and flags.no_welcome_mail suppress the attempt.

label is charset-gated to [A-Za-z0-9][A-Za-z0-9_-]*; it is both the revocation handle and the local-part of an email address, and two consumers sharing it are one identity that revoke each other.

Roles are reconciled, not merely added (dropping a role from the plug must actually take the capability away), through append_roles + a single save() rather than add_roles/remove_roles, which save on every call (G6). A role that does not exist on the site is a refusal, not a silent drop, because a silently-dropped role produces exactly the same under-privileged user as granting none.

The credential is created-if-absent and otherwise republished verbatim. This is the one deliberate divergence from the gitlab socket, and it is forced from both ends:

  • provider end: unlike a GitLab PAT, a Frappe api_secret is readable back (G3). Stability is available here and was not there.
  • consumer end: the consumer must SEAL the value to get it into compose (G9), and that seal is mint-once (G10). A rotating secret would diverge from its own seal on deploy two and stay diverged forever, with the sidecar presenting a credential the provider had already replaced.

generate_keys is therefore not used at all: it is a rotator (G5).

Everything is read back before it is published: enabled flag, api_key, the secret read the way frappe’s own authenticator reads it, user_type == "System User" (G6), and the exact role set. Coordinates and verdicts are printed; values never are.

It disables and de-keys; it does not delete. A Frappe User is referenced by owner and modified_by on every document it ever touched, plus Version, Comment and Activity Log rows; deleting it either fails link validation or rewrites history. Disabling is what actually closes the door; frappe’s authenticator filters enabled=True (G3), and the key pair is cleared so the value the consumer may still hold in its vault matches nothing.

No lifetime: managed: that gate marks jobs that DESTROY a resource and is frozen closed today, so a gated job never runs. Releasing a credential this socket minted is not a destroy.


frappe stack medusa stack
┌───────────────────────┐ ┌────────────────────────────┐
│ jobs.integration │ │ │
│ grant-erpnext-api-key│ │ │
│ ├ create-if-absent │ │ │
│ ├ read back │ │ │
│ └ ::shc-connection- │──── mint-and-return ─┼─▶ post_install hook render │
│ value::apiSecret │ (ce G9) │ medusa-erpnext-arm │
└───────────────────────┘ │ ├ probe 1: authn │
▲ │ ├ probe 2: authz │
│ Authorization: token k:s │ └ ::shc-hook:secret:: │
│ X-Frappe-Site-Name: <site> (G2) │ │ │
│ │ ▼ vault (G10) │
└────────────────────────────────────┼──── vars.erpnext.apiSecret │
│ │ │
│ ▼ NEXT deploy │
│ medusa-erpnext-sync │
└────────────────────────────┘

The proof is two requests, not one. frappe.auth.get_logged_user is @frappe.whitelist() (frappe/auth.py:433) and answers for any authenticated identity, roles or not, so it proves authentication and its return value proves which identity, but a green probe there would still be green for a credential that 403s on every business read. The second request reads /api/resource/Item and is what proves authorization. A 403 prints the role fix; a 404 prints the site-header diagnosis (G2); “authenticated as Guest” prints the swallowed-header diagnosis (G4).

The sidecar is armed on the second deploy. The mint reaches the hook render and never the compose render (G9), so the credential gets into compose only by way of the vault seal, which the next render reads. This is the identical caveat gitlab’s Sentry seal carries (“reaches GITLAB_OMNIBUS_CONFIG on the NEXT deploy”) and it is a property of the channel, not of this app. It is also why the probe matters so much: the probe is the only thing that runs on deploy one, and it is what turns “the edge is bound” from a claim into a fact.

Divergence fails loudly here, where gitlab’s seal exits 0. Same shape, different cost: a stale Sentry DSN means error reports go nowhere (degraded); a stale ERPNext key means the sidecar authenticates with nothing: no stock, no prices, no orders, and a storefront quietly selling from a frozen catalogue. That earns an X500908HKFAIL (logged loudly, stack stays up) rather than a line in a job log nobody reads.

The asymmetry, named. One end of this edge has a first-class revocable identity; the other has an administrator password (MEDUSA_ADMIN_EMAIL / MEDUSA_ADMIN_PASSWORD). That is Medusa’s shape, not ours; see §7 for what is owed.


5. The sync contract: the program nobody has written

Section titled “5. The sync contract: the program nobody has written”

vars.erpnext.syncImage is empty and the medusa-erpnext-sync service does not render without it (G11). This section is what an image must implement to be nameable there. It is a contract, not a description of something that exists.

  1. Send X-Frappe-Site-Name: <ERPNEXT_SITE> on every ERPNext request. Without it every call 404s, authenticated or not (G2). If the bridge does one thing right, this is it.
  2. Idle, never crash, on an empty credential. ERPNEXT_API_KEY / ERPNEXT_API_SECRET are empty on the deploy that first binds the edge (§4). The bridge must log once per interval and keep the container up, so the post-install hook has something to exec into and so restart: unless-stopped is not a crash-loop.
  3. Refuse to start on a missing ERPNEXT_COMPANY or ERPNEXT_WAREHOUSE. Do not guess. A wrong Company posts to the wrong ledger; a stock figure summed across warehouses is not sellable stock.
  4. One serialised loop. Do not interleave a stock write with an order write against the same Item. x-shc-scale.max: 1 enforces one replica for the same reason.
  5. Never write into ERPNext what ERPNext owns. The bridge creates sales documents and customers; it does not edit Items, prices, or stock levels.
stepERPNext readMedusa write
catalogueGET /api/resource/Item filtered disabled=0, is_sales_item=1, and item_group=ERPNEXT_ITEM_GROUP when setupsert Product, keyed by Item.name
variantsItem Variant / Item.variant_ofProduct variants, keyed by the child Item.name
stockGET /api/resource/Bin filtered warehouse=ERPNEXT_WAREHOUSEabsolute inventory level per variant
priceGET /api/resource/Item Price filtered price_list=ERPNEXT_PRICE_LIST, needs Sales Master Manager (G7); skip the whole step when ERPNEXT_PRICE_LIST is emptyvariant price
  • The join key is Item.name, carried on the Medusa side in external_id/metadata. Never the SKU: an ERPNext item_code is editable and a Medusa handle is user-facing.
  • Stock is absolute, not a delta. ERPNext’s Bin.actual_qty is the truth and the bridge overwrites. This is why ordering matters and why one replica is enforced.
  • actual_qty, not a sum. Reserved-quantity semantics (reserved_qty, projected_qty) are a policy choice; expose it as a var before changing it, do not fold it in silently.
  • Paginate. limit_start/limit_page_length; hold one page at a time (the 512M limit is sized for that).
  • Use modified as the cursor. ERPNext stamps it on every doctype; filter ["modified", ">", <last-success>] and keep the watermark in the bridge’s own Medusa metadata, so the bridge holds no durable state of its own; which is what lets it have no volume and lets a disconnect be a no-op.
triggerMedusa readERPNext write
new orderGET /admin/orders since watermarkCustomer (create-if-absent, needs ERPNEXT_CUSTOMER_GROUP + ERPNEXT_TERRITORY), then Sales Order
capture / refundorder payment collectionsPayment Entry against the Sales Order
  • Idempotency key: the Medusa order id, written into a field on the Sales Order and checked before insert. A duplicated push is the failure mode that costs real money.
  • ERPNEXT_SUBMIT_SALES_ORDERS defaults to false: orders land as DRAFTS. Deliberately timid: a submitted Sales Order reserves stock and is only reversible by cancel+amend, so an unattended sync that submits turns every storefront mistake into an accounting correction.
  • Never delete. A cancelled Medusa order becomes a cancellation document, not a deletion.
  • Log a one-line summary per cycle: items seen / updated, stock updated, orders pushed, errors. It is the only observability this edge has.
  • Exit non-zero only on a configuration error (missing Company/Warehouse). A transport failure is a retry, not a death; the ERP being down must not take the storefront’s stack with it.
  • Expose a health endpoint. compose.yaml deliberately declares no healthcheck today because the image is operator-named and a probe invented here would report a state nobody measured; when a real image exists, its probe belongs in that file.

Phase 1: LANDED with this change. The credential edge, proven. shc install medusa --stack shop -i postgres=pg -i erpnext=<frappe-stack>: the socket gates on erpnext-on-bench, mints the scoped Frappe User, the arm hook proves both authentication and authorization from inside medusa’s stack and seals the pair. No sidecar renders. This is a coherent resting state, not a half-built one; the estate has a verified, revocable ERPNext edge with nothing running on it, and every later phase starts from a credential that has already been proven rather than assumed.

Phase 2: the read-only pull. Build a bridge to §5.2 only, name it in vars.erpnext.syncImage, redeploy. Read-only against ERPNext, so the blast radius is Medusa’s catalogue. Ship this alone and let it run before writing a line of §5.3.

Phase 3: the order push. §5.3 with submitSalesOrders: false. Drafts only; a human submits. Promote to submitted only after the idempotency key has been observed to hold under a real duplicate.

Phase 4: payments. Payment Entry reconciliation. Out of scope here and deliberately last: it is the half where a bug is a ledger correction.


Owed on the provider side (outside this change’s surface, another agent is live-probing that package):

  • apps/platform/frappe/tests/tests.bats has no guards for any of this. What it needs, in order: (1) list-apps names erpnext on the pinned image; (2) jobs.discovery FAILS on a bench without erpnext; (3) the mint creates shc-<label>@integration.invalid reading back enabled, System User, and exactly the granted roles; (4) a second run republishes the identical key pair, the stability property the consumer’s mint-once seal depends on, and the one most likely to regress; (5) an authenticated frappe.auth.get_logged_user with X-Frappe-Site-Name returns the minted user and the same request without that header returns 404 (G2 asserted as a fact, not a comment); (6) the revoke leaves the user present, disabled and de-keyed, and is a clean no-op on a second run.
  • apps/platform/frappe/{vars,app}.yaml declare no publicUrl. The socket therefore publishes empty url/apiUrl (guarded with | default(''), so it renders rather than errors) and every consumer uses the internal pair. It cannot be derived from vars.siteName: on both live production benches the public hostname and the site name differ, which is the symlink case compose.yaml documents. Declaring publicUrl@url there is a small, clean change that this surface could not make.

Owed on the consumer side:

  • A dedicated Medusa user for the bridge. Today it authenticates as the seeded administrator. A medusa user seeded by an init job does not narrow the capability (every Medusa admin is equally powerful) but it makes revocation possible without locking the operator out. Medusa v2 offers nothing better; there are no API tokens and no roles.
  • A healthcheck on the sidecar, once an image exists (§5.4).
  • A live end-to-end test. Every guard shipped here is static, deliberately: driving this edge needs a frappe stack with erpnext activated, which is a multi-gigabyte second stack and a several-minute boot, and hanging it off medusa’s suite would make every medusa change wait on it. It belongs in the provider’s suite.

Unknowns, stated rather than papered over:

  1. No sync image exists and none is being written by this change. Phase 1 ships without one on purpose.
  2. gitlab.com/bitspur/community/medusa-erpnext-sync could not be definitively ruled out. The unauthenticated GitLab API says 404 Project Not Found; GitLab returns 404 for private projects to unauthenticated callers, and the on-box token at ~/.tokens/gitlab is expired (401), so “absent” and “private” are indistinguishable from here. Someone with a live token should check before anyone writes §5 from scratch. Nothing in this change pins it.
  3. Nothing here has run against a live ERPNext. The erpnext-bitspur MCP endpoint failed DNS resolution (getaddrinfo ENOTFOUND hq.bitspur.com) during this work, so every ERPNext claim above is sourced from erpnext / frappe version-15 source rather than from a live instance. The mint’s Python is syntax-checked and every shell body passes sh -n; neither has been executed inside a frappe container. That is the single largest gap between this document and reality.
  4. The Desk User role appears in Item’s permission list on version-15 and is not in the default grant. If a v15 bench turns out to require it for desk access, the mint’s user_type != "System User" read-back is what will catch it, loudly, at bind time, naming the field. That is by design, but it has not been observed.
  5. Multi-site benches are refused, not supported. This socket is per-site because the site name is the address (G2). A bench serving two sites needs vars.siteName to name the one it serves; serving both would need two sockets, which the current socket model has no shape for.
  6. erpnext.__version__ is read best-effort and never fatal. If the attribute moves the version publishes empty and nothing breaks.

alternativewhy not
Adopt aerele/medusa_integrationInverts the credential direction (ERPNext holds a Medusa admin password), runs provider-side as a bench app, and carries ~25 bespoke storefront DocTypes + ~20 core-doctype customisations, one integrator’s client build, not a mechanism (G11).
Compile the sync into our Medusa image as a SubscriberAvailable, and refused on coupling: sync fixes become image rebuilds, a sync crash-loop becomes a checkout crash-loop, and the pull half has no event to subscribe to (§2).
Name the socket erpOutcome name with a dozen unrelated faces; no consumer could write against it (§1).
Name the socket frappeThat is the framework; a bare Frappe bench has none of the doctypes this contract is made of (§1).
generate_keys for the mintIt is a rotator (G5), and a rotating secret diverges permanently from the consumer’s mint-once seal (G10, §3.2).
Revoke-then-mint, like the gitlab socketSame reason. The property that forces gitlab’s choice (a PAT’s plaintext is unrecoverable) does not hold for frappe (G3).
Delete the minted User on disconnectIt owns document history through owner/modified_by on everything it touched; deleting either fails link validation or rewrites history (§3.3).
Put the bind in the plug’s jobs.post_deploymentIt renders from the statically rendered socket data, where the credential is the empty string the socket publishes on purpose. It would seal two empty strings and report success (G9).
Pin medusa or valkey in the plug’s services:A pinned service becomes a DNS alias on the provider’s network; valkey would shadow frappe’s own valkey for every frappe service resolving the bare name.
Publish the ERPNext admin password / mysql credentials on the socketA socket data: block renders once per provider with no per-consumer variation to gate on; anything there goes to every consumer.
Include Sales Master Manager in the default grantIt is the only role that can read Item Price on version-15 and it is read+write over pricing masters (G7). The decision belongs to the operator, in the open.
Give the sidecar a healthcheck nowThe image is operator-named; a probe invented here would report a state nobody measured.