Skip to content

ADR-0017: Two boundary tiers, Tier 1 cloud-private as default

Status: Accepted — product brief (2026-06) Principles served: I Source: docs/design.md D7 (and risks 1, 7); docs/problem.md carried-forward item 3; .specify/memory/constitution.md Principle I

Context

No prompt, generated code, data, model input or output, or telemetry may leave the customer-controlled boundary — but self-hosted open-weight models may underdeliver prompt-to-app quality, a known risk accepted at the product gate. The working assumption is that most customers run in cloud, where private managed model endpoints satisfy the boundary requirement without the quality risk.

Decision

A single internal inference gateway abstracts all model access, with two configured tiers:

  • Tier 1 (cloud-private, the default): private managed endpoints (Bedrock-class) in the customer's own cloud tenancy and region, with provider retention and training disabled contractually and the enforcing configuration verifiable and recorded.
  • Tier 2 (self-hosted): vLLM-class serving on customer-operated infrastructure with no external model calls. Reserved, and not exercised — this decision records the tier as a design position; nothing implements it and no installation has selected it.

All builder and platform telemetry stays in-boundary in both tiers. Model swap is configuration, not code. Sovereignty claims are scoped honestly: platform and data jurisdiction is customer-controlled; model-endpoint jurisdiction is tier-dependent and is never marketed as blanket "no foreign jurisdiction" — Tier 1's default routes inference through a US hyperscaler's private endpoints, and buyers who require model-layer jurisdiction too are offered EU-resident or self-hosted endpoints.

Alternatives considered

  • Tier 2 (self-hosted) only — rejected as the default: open-weight model quality on the strict tier is a known risk; Tier 1 is the default sell, with a Tier 2 quality spike required before any strict-tier commitment (trigger: first defense/air-gapped prospect).
  • Direct provider model APIs from the builder — rejected: bypasses the boundary gateway where tier enforcement, telemetry, and identity live.

Consequences

The strict-tier quality risk is isolated behind the gateway, and switching models or tiers is a config change. The tier configuration itself becomes evidence — the enforcing configuration is recorded and verifiable. The honest-scoping requirement is a standing constraint on marketing and sales language, recorded in the brief precisely so the sovereignty wedge is not overclaimed.