Skip to main content

​
Context

@Replaces(Port) binds a custom driver over a port’s shipped drivers for the whole container (0263, 0306 decision 9). It cannot pick a provider per tenant or per country. Payments, SMS, WhatsApp, fiscal clearance, KYC, shipping, accounting and AI do exactly that: a KSA tenant charges through a KSA gateway, an Academorix tenant may bring its own SMS account. 0308 rule 4 lets a Connection’s fields override an Integration’s, but that covers credentials, not the choice of provider. The adapter readiness report asked for one rule before payments and fiscal are built. The owner decided it on 2026-10-25 (round-3 #8, with OS-74), and in round 22 kept Figentra’s own provider choices in the Figentra OS ADRs.

​
Decision

  1. @Replaces stays global. It swaps the driver class of a port for every tenant in that deployment. It is never used to choose a provider per tenant, market or legal entity.
  2. The Connection chooses the provider. A capability that has more than one provider (a port with several driver Integrations) resolves the provider for a call from the tenant’s Connection for that capability, found at the scope by walking the Integration’s declared levels (0308 rule 9). The driver bound to that Connection’s Integration serves the call.
  3. Market default. When the tenant has no Connection for the capability, the platform’s default for the Market applies: a platform Connection set per Market and capability (0244). For payments the Market is the checkout’s Market, which already carries the payment methods and processors (0244 decision 1).
  4. Two ways to get a provider. For each capability that offers both, the tenant uses either:
    • platform-provided: the platform’s provider account, through a platform Connection; the tenant pays the platform (for example in credits or a platform rate); or
    • bring your own: the tenant connects its own provider account from the app market (0355) and pays the provider directly. Payments (0357 decision 3), messaging (SMS, WhatsApp, push), AI model keys and other provider accounts and OAuth apps (0308 rule 11) all use this rule. Which plans may bring their own account is the product’s choice.
  5. Platform market defaults are data, not code. The default provider per Market for a capability is set as platform configuration, so a change of default is not a release.
  6. Sandboxes. Sandbox behaviour (test-mode gateways, captured messages, test endpoints) is in 0359 decision 11, whichever way the provider was chosen.
  7. Failover across a capability’s providers is a driver feature of the port; on which accounts it is on is the product’s choice.
  8. Figentra’s choices. Figentra’s default providers per Market (for example its SMS defaults), the fees and credits it charges, which plans may bring their own accounts, OAuth apps or AI keys, and failover on tenant accounts are Figentra OS ADRs 0028, 0034, 0035, 0047, 0049 and 0067 (owner round 22, 0259).

​
Consequences

  • Payments, messaging, fiscal, KYC, shipping, accounting and AI share one rule for picking a provider, so no service invents its own country switch.
  • A new market is a new set of platform Connections and defaults, not a code change.
  • Every multi-provider capability needs a port with a driver per provider, each an Integration (0355 decision 1).
  • The hosted Connection store with per-tenant encryption (round-3 #10, OS integrations) must exist before any per-tenant provider runs in production.

​
Enforcement

planned — a ConnectionContext driver in @stackra/integrations that resolves the tenant Connection, then the market default; a conformance test per multi-provider port (tenant Connection wins; no Connection gives the market default; @Replaces changes the driver class only); a gen or validator check that refuses @Replaces code that branches on the tenant or the Market.

​
Open questions

  1. Which Market keys the default for non-payment capabilities. For SMS and WhatsApp it could be the tenant’s Market or the recipient’s country; for fiscal it could be the legal entity. Not decided.
  2. Fallback from a failing tenant Connection. Whether a call falls back to the Figentra-provided provider when the tenant’s own Connection fails, or refuses, is not decided. OS-219 says connections are never auto-disconnected; it does not say whether calls switch provider.
  3. Several tenant Connections for one capability (for example two gateways in one Market): which serves a call is not decided beyond 0308 rule 10 (connection_ambiguous).

​
Supersedes and sources

Supersedes: none. Reads with 0263, 0308, 0244, 0219 decision 2 and 0156. Sources: owner decisions in chat, 2026-10-25: round-3 questionnaire 8 and 10 (notes/handover/360/questionnaire-round-3.md); Commerce questionnaire Answers, 27 (gateways chosen per tenant and market through the Connection); OS answers OS-74, OS-93 and OS-313, and the defaults OS-18, OS-186, OS-188, OS-202, OS-216 and OS-219 (notes/handover/os/); 360/adapter-readiness-and-missing-packages.md finding 1 and action 4.