qbit-scripting/supervisor/NATIVE-QUALIFICATION.md

# Explicit trusted native qualification recipe

This driver is excluded from Surefire discovery. It is not executed by `verify`, does not accept author submissions and cannot create a production evidence ID. Root owns its actual isolated Linux execution. Nothing below authorizes a host-runtime installation or deployment.

The source driver is `src/test/java/com/kingsrook/scripting/supervisor/NativeSupervisorQualification.java`. Its only helper is `TlsIdentity.java`; all nested Counted/Client/anonymous lifecycle classes generated from the driver must be present. It uses runtime JNA/json dependencies only, not JUnit. `test-compile` with Checkstyle passed at2026-10-31T10:29:30-05:00; this proves compilation, not native execution.

From the qbit-scripting root, with the already pinned Node24.22.2 binary and installed worker dependencies:

```powershell
& node worker/node_modules/typescript/bin/tsc -p worker/tsconfig.json   # exact Node 24.22.2 required
& node supervisor/fixtures/compile-trusted.mjs   # exact Node 24.22.2 required
.\mvnw.cmd -o -f supervisor/pom.xml test-compile
```

The first command refreshes only the existing trusted compiler's JS output. The generator calls the actual worker strict compiler on four fixed synthetic TypeScript projects. It does not run emitted code. `target/native-fixtures` receives exact ESM bundles, source requests and a hash manifest. The Unicode fixture spans three bounded source files and intentionally emits over1MiB UTF8 while remaining under1Mi UTF16/2MiB UTF8. Do not replace these outputs with handwritten ESM while claiming compiler-path proof.

Freeze and hash the module's main/test classes, JNA5.18.1 and json20251224 JARs, fixture directory, exact Extism1.41.0 native library and fixed sibling Wasm. Run only those snapshots in the bounded root-owned Linux container. Example paths inside that container:

```text
java -cp '/qualification/classes:/qualification/test-classes:/qualification/lib/*' \
  com.kingsrook.scripting.supervisor.NativeSupervisorQualification \
  /qualification/native/libextism.so ACTUAL_NATIVE_SHA256 \
  /qualification/runtime/qqq_javy_runtime.wasm ACTUAL_WASM_SHA256 \
  /qualification/fixtures
```

Java21 plus keytool are required. The driver binds only an ephemeral loopback port and generates a short-lived test certificate in its private temporary directory; it never receives production keys or tokens. Permit that owned loopback communication while denying external egress. Provide bounded writable temporary space for ephemeral identity/JNA extraction, readonly snapshots for the exact libraries/runtime/fixtures, no host environment secrets, no guest preopens and finite outer CPU/memory/pids/time/output limits. Containerization itself is not qualification.

Assertions cover actual TLS PREPARE→READY→RETIRED, original.ts/emitted.js identity, static relative modules/live binding/top-level await, awaited SDK broker, four fresh counter/time/random/context calls, Unicode boundary, generic script-error handling followed by a normal call, actual CPU/wall usage and counted native cleanup before every retirement. A mismatched memory profile must refuse before constructing a new instance. Separate direct calls prove that the host binding refuses a second call on one instance and that the same small normal preparation fails under fuel1; no infinite loop, allocation bomb or escape payload is used.

The printed JSON contains only fixed scope, public binary hashes, counts, measured usage and `productionQualified:false`. It is a correctness corpus, **not a latency benchmark**. Random-value variation is evidence of this fixed repeated-state fixture, not cryptographic randomness qualification. Low-fuel refusal is not proof of complete CPU or native-callback accounting. Full containment/import inventory, quantitative cancellation/free overshoot, memory-pressure behavior, real application PersistentWorkerProvider interoperability, strict cold compiler service and Kubernetes deployment remain separate gates.

On failure preserve the exact snapshot, full private test log and sanitized failure code; do not silently rerun with larger budgets or alter expected values. Successful test output must name the actual binary hashes and source snapshot.