Move docs/ package mirror into document-navigator plugin

Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-30 01:10:00 +01:00
parent fe3fedf42e
commit 9bf56a806b
6022 changed files with 12437 additions and 0 deletions

View File

@@ -0,0 +1,69 @@
# run-wasm-conformance
<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose
Exports `runWasmSandboxConformance(label, makeSandbox)` — the
conformance harness every WASM-tier sandbox host (this package's own,
or any future implementation) MUST pass. The harness pins the
observable contract: preopens reflect `policy.fs[]`, the outbound
allowlist reflects `policy.fetch[]`, the `rw:` prefix turns a preopen
read-write, `dispose()` is idempotent, and the instrument registry
exposes the canonical `plugin.permission_denied_total` counter.
The harness is exported from the `./testing` subpath so adapters
consume it as a normal import. The in-package fixture sandbox passes
every scenario; the harness is self-tested via
`run-wasm-conformance.test.ts`.
## Features
- Six pinned scenarios covering the spec delta's observable behaviour.
- Uses the host's `describe`/`it` from `@suaveplan/testing/runner` so
adapter test reports show nested suites under the host's tree.
- `WasmSandboxFactory` signature lets adapters pass a minimal builder
rather than re-implementing the full `createWasmSandbox` surface.
## Usage: Basic
```ts
// In an adapter package's test file:
import { runWasmSandboxConformance } from "@suaveplan/api-sandbox-wasm/testing";
import { makeMyAdapterSandbox } from "./my-adapter.js";
runWasmSandboxConformance("my-adapter", makeMyAdapterSandbox);
```
## Usage: Advanced
```ts
runWasmSandboxConformance("with-cache", async (input) => {
const cached = sandboxCache.get(JSON.stringify(input));
if (cached !== undefined) return cached;
const handle = await createWasmSandbox({ /* ... */ });
sandboxCache.set(JSON.stringify(input), handle);
return handle;
});
```
## API Reference
- `runWasmSandboxConformance(label: string, makeSandbox: WasmSandboxFactory): void`
- `WasmSandboxFactory = (input) => Promise<WasmSandboxHandle>` where
`input` is `{ fsRules, fetchRules, denyCapability }`.
## Implementation Notes
The harness consumes the adapter's `WasmSandboxHandle` via its public
surface only — `preopens`, `outbound`, `instruments`, and `dispose()`.
Adapters that wrap or proxy the handle must preserve those properties
identically.
The harness deliberately uses `dispose()` after every scenario rather
than letting GC handle it, because a WASM-runtime under load can pin
memory longer than the test budget allows. Adapters that hold open OS
resources MUST close them in `dispose()` for the harness to pass on
constrained CI runners.