# HyperTwist Provider Neutrality And BYOK Doctrine - 2026-05-21

## Interpretation rule

If HyperTwist uses the phrase `OpenAPI BYOK`, treat it as
`OpenAI-compatible custom-endpoint BYOK` unless a later HyperTwist document
defines a stricter internal meaning.

The goal is provider-neutral model access with first-party key/profile
custody, not vendor lock-in.

## Purpose

This doctrine closes the gap between provider-specific donor value and the
actual product requirement for provider-neutral implementation.

It exists to answer clearly:

1. whether provider-specific donors are allowed to hard-wire the product to
   one vendor
2. how later implementation should generalize single-provider donors
3. where OpenAI-compatible custom endpoints and BYOK fit
4. which slices must stay first-party even when adjunct provider donors are
   later retained

## Core rule

HyperTwist must be provider-neutral at the top-level product-contract layer.

That means:

- no donor is allowed to force product-wide single-provider coupling
- provider-specific donor logic may survive only as bounded adapter, polling,
  telemetry, UI-pattern, or workflow-pattern behavior
- operator-facing surfaces such as usage, cost, routing, health, provider
  settings, or model choice must consume first-party normalized provider
  contracts

The retained donor may be provider-specific.

The implemented product must not be.

## Current evidence posture

HyperTwist already contains first-party provider/session seams in current code:

- `HyperTwistRecognitionTypes`
- `UHyperTwistHttpVisionClient`
- `UHyperTwistHttpSpeechClient`
- `UHyperTwistMockSpeechClient`
- `UHyperTwistTrainingSubsystem`

Those seams prove that HyperTwist already owns bounded provider contracts for:

- session config
- session open/close
- transcript/result payloads
- health/status envelopes
- provider-routing policy ids and definitions
- route-decision summaries and fallback-health posture

Treat those as the current first-party `A1` anchor for recognition,
speech-provider contracts, and bounded provider routing/policy ownership.

Do not let future provider donors overtake that top-level contract by
accident.

## Core contract rules

- HyperTwist top-level provider contract must be first-party and
  provider-neutral
- provider-specific donors may contribute bounded UI, adapter, telemetry,
  polling, or workflow patterns only
- no provider-specific donor may define the top-level product contract by
  accident
- OpenAI-compatible custom endpoints are first-class targets
- first-party BYOK custody, provider profiles, endpoint definitions, and
  model-profile mapping remain HyperTwist-owned

## Required provider classes

The first-party provider contract must support at least:

1. official/direct provider integrations
2. OpenAI-compatible API endpoints
3. BYOK endpoints
4. managed gateway providers
5. local/self-hosted providers
6. bounded speech/vision sidecar services

## Normalization rules

The normalized provider contract should expose at least:

- provider identity
- profile identity
- model identity
- endpoint class
- auth source
- capability flags
- usage metrics
- cost metrics
- quota/rate-limit state
- health state
- session state
- workflow-policy state

UI layers should read that normalized state.

They should not talk directly to one upstream provider unless they are a
bounded adapter surface.

## Provider-lane separation

Keep these lanes distinct:

1. provider contract lane
2. routing/gateway lane
3. provider-profile and BYOK custody lane
4. normalized usage/cost accounting lane
5. provider-specific overlay/presentation lane
6. provider-specific local log/telemetry ingestion lane
7. admin/policy lane

## Current authority map by slice

### Provider contract lane

- `A1 / R1 / F1` - first-party HyperTwist contract ownership
- current evidence anchor:
  - `HyperTwistRecognitionTypes`
  - `UHyperTwistHttpVisionClient`
  - `UHyperTwistHttpSpeechClient`

### Routing/gateway lane

- `A1 / R1 / F1` - first-party only for the bounded routing/policy layer
- current evidence anchor:
  - `FHyperTwistSpeechProviderRoutingPolicy`
  - `FHyperTwistSpeechProviderRouteDecision`
  - `UHyperTwistTrainingSubsystem`

### Provider-profile and BYOK custody lane

- `A1 / R1 / F1` - first-party only

### Normalized usage/cost accounting lane

- `A1 / R1 / F1` - first-party only for the normalized usage/cost event-model
  lane
- current evidence anchor:
  - `FHyperTwistSpeechUsageCostAccountingProfile`
  - `FHyperTwistSpeechNormalizedUsageEvent`
  - `FHyperTwistSpeechNormalizedCostEvent`
  - `FHyperTwistSpeechQuotaRateLimitState`
  - `UHyperTwistTrainingSubsystem`

### Provider-specific overlay/presentation lane

- provider-specific donors, if retained later, may become `A2` adjuncts for
  narrow UI patterns
- they do not own the top-level provider contract

### Provider-specific local log/telemetry ingestion lane

- owner unresolved in current HyperTwist packet set
- may later be informed by provider-specific donors or local runtime tooling

### Admin/policy lane

- `A1 / R1 / F1` - first-party only
- current evidence anchor:
  - `FHyperTwistSpeechProviderRoutingPolicy`
  - `FHyperTwistSpeechProviderRouteDecision`
  - `UHyperTwistTrainingSubsystem`

## BYOK rules

BYOK must be a first-party capability, not a donor side effect.

That means:

- user-supplied API keys remain first-party owned
- user-supplied custom base URLs/OpenAI-compatible endpoints remain
  first-party owned
- provider profiles must support:
  - official providers
  - OpenAI-compatible custom endpoints
  - user-labeled BYOK profiles
  - per-profile model lists or capability maps
  - per-profile auth material
  - enable/disable controls
- provider-specific adapters must plug into that first-party profile model
  rather than creating parallel key custody

## Anti-lock-in rules

- no hard requirement on one vendor for the primary user path
- no product setting or menu may assume only one provider exists
- no core feature may require one specific provider if a normalized first-party
  path is possible
- provider-specific enhancements must degrade gracefully when that provider is
  disabled

## Implementation rules

The correct implementation order is:

1. first-party provider contract
2. first-party provider profile and BYOK custody surfaces
3. routing and policy layer
4. normalized usage/cost event model
5. operator-facing overlay/dashboard surfaces
6. bounded provider-specific adapters where still useful

Current landed ordering status:

- steps `1` through `5` now have bounded first-party implementation anchors
- operator-facing usage/cost history/export shells now also have a bounded
  first-party implementation anchor
- provider receipt review and posted-charge inspection now also have a bounded
  first-party implementation anchor
- provider billing settlement and invoice reconciliation now also have a
  bounded first-party implementation anchor
- provider settlement exception and external-portal handoff now also have a
  bounded first-party implementation anchor
- real device-permission workflow now also has a bounded first-party
  implementation anchor above the landed permission/readiness shell posture
- native capture-route ownership and workflow now also has a bounded
  first-party implementation anchor above the landed readiness and
  permission-workflow seams
- operator-facing native capture-route workflow shell now also has a bounded
  first-party implementation anchor above the landed workflow/control seam
- provider-neutral custom-endpoint runtime routing now also has a bounded
  first-party implementation anchor above the landed provider-profile/BYOK and
  provider-routing seams
- actual payment execution or provider-portal ownership remains later
  first-party work
- provider-specific adapters remain later work

Do not invert that order.

If HyperTwist starts from a provider-specific overlay and only later tries to
generalize, it will accumulate brittle vendor coupling in the wrong layer.

## Donor adoption rule

Provider-specific donors may still be strongest for narrow slices.

That does not let them own:

- the top-level provider contract
- key custody
- profile ownership
- global routing language

License posture affects route, not capability rank.

But top-level provider contract ownership remains first-party and
provider-neutral.

## Retroactive backfill rule

If an earlier HyperTwist packet accidentally let a provider-specific donor
over-shape the top-level contract:

- reopen that packet selectively
- preserve valid bounded provider-specific value
- demote contract ownership back to first-party normalized interfaces
- do not bulk-rewrite history
- do not invent certainty

## Relationship to active doctrine

Use this doctrine with:

- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md`
- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md`
- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ARCHITECTURE.md`
- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ROADMAP.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\README.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\MODEL_OUTPUT_RULES.md`

## Canonical decision sentence

Provider-specific retained repos may survive as bounded donors, but every
implemented HyperTwist usage, cost, routing, health, or settings surface must
resolve through first-party provider-neutral contracts with OpenAI-compatible
custom-endpoint and BYOK support.
