Initial Commit

packages/api-stack/api/api-host/src/testing/testing.md

@@ -0,0 +1,62 @@
+# `./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.