first commit

docs/api-stack/api/api-ws-bun/src/testing/conformance-binding.md

@@ -0,0 +1,63 @@
+# `conformance-binding`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Binds the abstract `runWsEngineConformance` harness from `@suaveplan/api-ws/testing` to a default `createBunWsEngine`-backed factory. Plugin authors who want to drop the conformance suite into their own integration tests import `runBunWsConformance` from `@suaveplan/api-ws-bun/testing` and get the full Stage-1 contract assertion set wired against the Bun engine in one line.
+
+The factory uses `@suaveplan/api-ws-broker-in-memory` so the conformance run has no external dependencies — every host that can run Bun + vitest can run the suite without standing up Redis.
+
+## Features
+
+- `bunEngineFactory()` — fresh engine/broker per scenario; no shared state.
+- `adaptEngineToFactory(engine, broker?)` — exposes a custom engine through the conformance factory contract.
+- `runBunWsConformance(options?)` — drop-in suite that defaults to `bunEngineFactory` but accepts a custom `label` / `factory` for plugin-specific wiring.
+- Re-export of `runWsEngineConformance` so the api-ws import is one hop away.
+
+## Usage: Basic
+
+```ts
+import { runBunWsConformance } from "@suaveplan/api-ws-bun/testing";
+
+runBunWsConformance();
+```
+
+## Usage: Advanced
+
+```ts
+import { createInMemoryWsBroker } from "@suaveplan/api-ws-broker-in-memory";
+import {
+    adaptEngineToFactory,
+    runBunWsConformance,
+} from "@suaveplan/api-ws-bun/testing";
+import { createBunWsEngine } from "@suaveplan/api-ws-bun";
+
+runBunWsConformance({
+    label: "bun-with-strict-heartbeat",
+    factory: () => {
+        const broker = createInMemoryWsBroker();
+        const engine = createBunWsEngine({
+            reconnectTokenSecret: new Uint8Array(32).fill(1),
+            broker,
+            heartbeatMs: 5_000,
+            missedPongLimit: 1,
+        });
+        return adaptEngineToFactory(engine, broker);
+    },
+});
+```
+
+## API Reference
+
+- `bunEngineFactory<Payload>(): WsEngineFactoryResult<Payload>` — default factory.
+- `adaptEngineToFactory<Payload>(engine, broker?): WsEngineFactoryResult<Payload>` — manual adapter.
+- `runBunWsConformance(options?): void` — convenience wrapper around `runWsEngineConformance`.
+
+## Implementation Notes
+
+`makeTestConnection` routes through the real `engine.attach(...)` path, so the conformance suite exercises the production handshake / registry / bus wiring rather than a stubbed registry add. This is the same property the api-ws contract package's `inMemoryFactory` achieves for the in-memory bus — once you accept the conformance contract, the implementation is tested too.
+
+The default factory's secret is a fixed `Uint8Array(32).fill(7)` — that is acceptable for tests because no test asserts on token contents across factory invocations. Production callers MUST supply their own secret via `createBunWsEngine` directly, never through this convenience factory.