Host API: Proposal: Split Core Host API and Extensions for Host API

Summary

Introduce a stable core host API alongside a formal extensions/experimental framework to allow new host features to be prototyped and iterated on before being promoted to the stable API.

---

Motivation

As the host API grows, there's a risk of either:

• Committing too early to interfaces that aren't fully proven, or
• Blocking useful new features from being available while they're still being designed.

A two-tier API model would let us ship new capabilities sooner while keeping the stable API clean and reliable.

---

Proposal

1. Core Host API

Define a stable, versioned core API for the host. This surface should have strong backward-compatibility guarantees and go through a proper review/stabilisation process before anything is added.

2. Extensions / Experimental Framework

Introduce a separate framework for experimental or in-progress host features. This would:

• Have a clearly marked interface (e.g. experimental namespace, feature flag, or separate import path)
• Is not exposed in App Store production builds — only available via TestFlight or internal builds
• Carry an explicit caveat that interfaces may change as development progresses
• Allow the team to prototype and validate new features with real usage before committing to a stable API shape

3. Graduation Path

Experimental features follow a defined process to graduate into the stable core API:

Prototype and internal testing under the experimental framework
TestFlight distribution for broader feedback
API stabilisation and review
Promotion to stable core and App Store release

---

Example Use Case

P2P discovery / data connections — this is a good candidate to prototype under the experimental framework first, gather feedback, and then graduate to the stable API once the interface is well understood.

---

Benefits

• Faster iteration on new host features without breaking stable consumers
• Clear signal to developers about what they can rely on vs. what may change
• Reduces pressure to "get it right first time" on the stable API
• Mirrors a pattern used successfully in other ecosystems (e.g. Rust's #[unstable], browser origin trials, TC39 stages)

---

Open Questions

• What should the experimental framework look like in practice — a separate package, a namespace, a flag?
• What are the criteria for graduating a feature from experimental to stable?
• How do we communicate breaking changes within the experimental layer?

Start by mapping the existing host API surface and its public entry points in the TypeScript SDK; the issue does not identify specific files or tests. Compare possible separation mechanisms for the stable core and experimental extensions, then document graduation criteria, distribution restrictions, and compatibility expectations as a decided design.