# `./testing` — RESERVED subpath

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`@suaveplan/api-host/testing` is a **reserved subpath** in API plugin system. The intent is to populate it  with `createTestHost` + the in-memory adapter wiring (`api-router-in-memory`, `api-auth-in-memory`, `api-db-sqlite-memory`, etc.). Stage 2 ships an intentionally-empty surface so downstream packages can declare a peer-dep on the documented path today, and bundler / TypeScript resolution succeeds before the helper actually exists. The package's primary build does not have to wait on The test harness.

The single named export, `STAGE_2_RESERVED`, is a sentinel marker — Stage 5 will replace it with the populated `createTestHost` API while keeping the same subpath. Probes that need to discriminate "reserved-but-empty Stage 2 release" from "Stage 5 populated surface" can branch on `STAGE_2_RESERVED === true`.

## Features

- Stable subpath export — `@suaveplan/api-host/testing` resolves in every release ≥ 0.1.0.
- Single named sentinel (`STAGE_2_RESERVED`) so the surface has zero runtime side effects.
- Type-checked at consumer build time without a runtime dependency on the host's drivers.
- Documented promotion path — Stage 5 replaces the sentinel with the real harness.

## Usage: Basic

```ts
import { STAGE_2_RESERVED } from "@suaveplan/api-host/testing";

if (STAGE_2_RESERVED) {
    // Hosting environment is on the reserved-but-empty Stage-2 release.
    throw new Error(
        "api-host/testing requires Stage-5 helpers — install once they ship."
    );
}
```

## Usage: Advanced

A downstream package that wants to consume the helper as soon as Stage 5 ships can declare an optional peer-dep on the subpath and gate-import it at runtime:

```ts
// in package.json
// "peerDependencies": { "@suaveplan/api-host": "^0.1.0" }
// "peerDependenciesMeta": { "@suaveplan/api-host": { "optional": true } }

// in code
const { STAGE_2_RESERVED, createTestHost } = (await import(
    "@suaveplan/api-host/testing"
)) as typeof import("@suaveplan/api-host/testing") & {
    createTestHost?: () => unknown;
};

if (!STAGE_2_RESERVED && createTestHost !== undefined) {
    const host = createTestHost();
    // ...
}
```

## API Reference

- `const STAGE_2_RESERVED: true` — sentinel; replaced with `false` (and populated exports) .
- `type Stage2Reserved = typeof STAGE_2_RESERVED` — kept stable so Stage 5 can layer in real types on the same path.

## Implementation Notes

The empty placeholder is not a stub. It is a deliberate subpath reservation documented in the proposal (§What changes → `./testing`) so consumers do not race ahead of Stage 5 and re-implement the helper out-of-tree. Replacing it later is a non-breaking change: the runtime surface grows, the type surface widens, and the sentinel flips from `true` to `false`. No consumer that wires only on the sentinel needs to update.