diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml
index 7c4ec8151..c52854102 100644
--- a/.github/workflows/build-and-test.yml
+++ b/.github/workflows/build-and-test.yml
@@ -163,8 +163,19 @@ jobs:
run : |
java -jar openaf.jar --install
cd tests
+ rm -f autoTestAll.results.json
../ojob autoTestAll.yaml
+ - name: Upload structured test results
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: test-results
+ path: |
+ tests/autoTestAll.results.json
+ tests/autoTestAllResults.xml
+ tests/autoTestAll.md
+
# ------------------------------------
- name: Convert autoTestAll.md to html
uses: openaf/ojob-action@v7
@@ -274,7 +285,7 @@ jobs:
# ------------------
- name: Test results
run : |
- grep -q '"fail":0' tests/autoTestAll.results.json || exit -1
+ python3 -c 'import json; r=json.load(open("tests/autoTestAll.results.json")); assert r.get("complete") is True and r["fail"] == 0 and r["count"] > 0 and not r.get("infrastructureErrors")'
languages:
needs: build
@@ -318,4 +329,37 @@ jobs:
if: always()
with:
name: language-results-${{ matrix.os }}
- path: tests/languages-results.json
+ path: |
+ tests/languages-results.json
+ tests/framework-results.json
+
+ test-framework:
+ needs: build
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, macos-latest, windows-latest]
+ java: ['21', '25']
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 10
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-java@v4
+ with:
+ java-version: ${{ matrix.java }}
+ distribution: temurin
+ - uses: actions/download-artifact@v4
+ with:
+ name: openaf.jar
+ path: .
+ - name: Test standalone framework
+ run: >-
+ java -Dopenaf.test.worker=true -jar openaf.jar -c
+ "try { loadLib('tests/runTestFramework.js'); exit(2); } catch(e) { printErr(e); exit(1); }"
+ - uses: actions/upload-artifact@v4
+ if: always()
+ with:
+ name: framework-results-${{ matrix.os }}-java${{ matrix.java }}
+ path: tests/framework-results.json
diff --git a/.github/workflows/publish-maven.yml b/.github/workflows/publish-maven.yml
index 3aad5a3ab..65183ec6b 100644
--- a/.github/workflows/publish-maven.yml
+++ b/.github/workflows/publish-maven.yml
@@ -84,8 +84,9 @@ jobs:
run: |
java -jar openaf.jar --install
cd tests
+ rm -f autoTestAll.results.json
../ojob autoTestAll.yaml
- python3 -c 'import json; r=json.load(open("autoTestAll.results.json")); assert r["fail"] == 0 and r["count"] > 0'
+ python3 -c 'import json; r=json.load(open("autoTestAll.results.json")); assert r.get("complete") is True and r["fail"] == 0 and r["count"] > 0 and not r.get("infrastructureErrors")'
- name: Snapshot tested binary and matching generated sources
working-directory: release
run: |
diff --git a/.gitignore b/.gitignore
index a5b26820d..e79e38354 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,3 +28,7 @@ maven-*
.github/workflows/*
!.github/workflows/publish-maven.yml
/tools/central/__pycache__/
+
+# ow.test generated validation artifacts
+/tests/framework-results.json
+/js/.openaf_precompiled/
diff --git a/AGENTS.md b/AGENTS.md
index da17ff91d..a3a0726e4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,7 +16,9 @@
## Coding Style & Naming Conventions
- Java: standard conventions (classes `CamelCase`, methods/fields `camelCase`, constants `UPPER_SNAKE`). Indent with 4 spaces, UTF‑8, LF endings.
- Java packages: keep under `openaf.*`; place new plugins in `src/openaf/plugins/` when appropriate.
-- JavaScript/YAML: 2‑space indent; end statements with semicolons in JS; filenames use kebab/camel to match neighbors.
+- JavaScript/YAML: use 2-space indentation in new code; preserve the surrounding indentation in existing blocks. Filenames use kebab/camel to match neighbors.
+- JavaScript: omit optional statement-ending semicolons in new code. Retain required separators in `for` headers, between same-line statements, and wherever automatic semicolon insertion would change parsing (for example before a following `(` or `[` expression). Keep spacing readable and avoid reformatting unrelated legacy code.
+- ODoc: place documentation immediately above the corresponding function or the registration block for generated methods. Use `` for Markdown content, backticks for API names and parameters, and CDATA for examples or XML-sensitive text. Preserve help keys/signatures and ensure moved module documentation remains included in generated help.
- No strict linter config is enforced; match surrounding style and minimize diff noise.
## Testing Guidelines
diff --git a/BUILD.md b/BUILD.md
index 4aaa2382c..3c45e034f 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -32,6 +32,11 @@ This will create two main files:
* openaf.jar
* openaf.jar.orig
+Compiler failures stop the build with a nonzero exit status. The build assembles
+and checks a temporary JAR before atomically replacing `openaf.jar`, preserving
+the previous JAR if compilation or assembly fails. Packaging steps run in order
+before the completed JAR is copied to `dist/`.
+
In an installed OpenAF directory, run `./oaf --repack` after replacing the JAR or
changing the JDK to refresh the `.shared.oaf` archive used by generated launchers.
Repacking trains and validates archive coverage while retaining the existing
@@ -53,6 +58,25 @@ cd tests
java --enable-native-access=ALL-UNNAMED -jar ../openaf.jar --ojob -e autoTestAll.yaml
```
+The browser table sorter and build failure regressions can also run independently
+from the repository root:
+
+```bash
+node tests/mdtablesort.cjs
+python3 tests/build-failures.py --bootstrap /path/to/existing/openaf.jar
+```
+
+The build regression uses a temporary copy and injected compiler failures,
+including large diagnostics, to verify failure status and preservation of the
+previous JAR. It requires a POSIX shell. To exercise subprocess pipe pressure,
+timeouts and cancellation against the rebuilt classes:
+
+```bash
+mkdir -p /tmp/openaf-shell-tests
+javac -cp 'bin:openaf.jar:lib/*' -d /tmp/openaf-shell-tests tests/java/ShellProcessTest.java
+java -cp '/tmp/openaf-shell-tests:bin:openaf.jar:lib/*' ShellProcessTest
+```
+
### Optional Maven Central distribution
See [Maven Central publishing](docs/dev/maven-central-publishing.md) for the
diff --git a/build.yaml b/build.yaml
index 52856f872..b206ae5b3 100644
--- a/build.yaml
+++ b/build.yaml
@@ -20,7 +20,11 @@ jobs:
- Build OpenAFOS
exec : |
log("Repacking...");
- $sh().envs({ __OAF_MAINCLASS: "openaf.Launcher" }, true).sh([ow.format.getJavaHome() + "/bin/java", "-jar", global.path + "/openaf.jar", "--repack"]).exec()
+ var result = $sh().envs({ __OAF_MAINCLASS: "openaf.Launcher" }, true).sh([ow.format.getJavaHome() + "/bin/java", "-jar", global.path + "/openaf.jar", "--repack"]).exec(0)
+ if (result.exitcode != 0) {
+ logErr("Repack failed: " + result.stderr + result.stdout)
+ exit(1)
+ }
var isOk = false, init = now()
do {
@@ -28,18 +32,22 @@ jobs:
if (!io.fileExists(global.path + "/openaf.jar.tmp")) isOk = true
} while (!isOk && now() - init < 60000)
+ if (!isOk) {
+ logErr("Repack did not finish within 60 seconds")
+ exit(1)
+ }
log("Repacked.")
# Copy OpenAF to the right place for use
- name : Copy OpenAF
deps :
+ - Prepare shell complete
- Prepare ojob saved
- Prepare ojob doc
- Build OpenAFOS
- Repack OpenAFOS
- exec : >
+ exec : |
log("Copying...");
- //sh("cp " + global.path + "/openaf.jar " + global.path + "/dist/openaf.jar", "", undefined, true);
io.mkdir(global.path + "/dist");
io.cp(global.path + "/openaf.jar", global.path + "/dist/openaf.jar");
@@ -47,6 +55,7 @@ jobs:
- name : Prepare ojob doc
deps :
- Repack OpenAFOS
+ - Prepare ojob saved
exec : |
sleep(1000, true)
@@ -90,6 +99,7 @@ jobs:
zip.close()
} catch(e) {
logErr("Error copying " + from + " to (openaf.jar)" + to + ": " + e)
+ exit(1)
}
}
try {
@@ -99,6 +109,7 @@ jobs:
zip.close()
} catch(e) {
logErr("Error copying " + from + " to (openaf.jar.orig)" + to + ": " + e)
+ exit(1)
}
}
@@ -141,8 +152,12 @@ jobs:
exec : |
sleep(1000, true)
- $sh([ow.format.getJavaHome() + "/bin/java", "-jar", global.path + "/openaf.jar", "-c", "ow.loadOJob();__flags.OJOB_CHECK_JOB_CHANGES=false;oJobRunFile('" + global.path + "/ojob.json');io.writeFileJSON('" + global.path + "/ojob.saved.json',$ch('oJob::jobs').getAll(), '')"])
- .exec()
+ var result = $sh([ow.format.getJavaHome() + "/bin/java", "-jar", global.path + "/openaf.jar", "-c", "ow.loadOJob();__flags.OJOB_CHECK_JOB_CHANGES=false;oJobRunFile('" + global.path + "/ojob.json');io.writeFileJSON('" + global.path + "/ojob.saved.json',$ch('oJob::jobs').getAll(), '')"])
+ .exec(0)
+ if (result.exitcode != 0) {
+ logErr("Generating saved jobs failed: " + result.stderr + result.stdout)
+ exit(1)
+ }
plugin("ZIP")
var zip = new ZIP()
@@ -154,6 +169,19 @@ jobs:
zip.streamPutFileStream(global.path + "/openaf.jar.orig", "ojob.saved.json", is)
is.close()
+ # ----------------------------
+ - name : Generate ODoc reference
+ deps :
+ - Repack OpenAFOS
+ exec : |
+ log("Generating ODoc reference...")
+ var result = $sh([ow.format.getJavaHome() + "/bin/java", "-jar", global.path + "/openaf.jar", "--ojob", "-e",
+ global.path + "/genODocReference.yaml dirs=js,src output=docs/ref"]).pwd(global.path).get(0)
+ if (result.exitcode != 0) {
+ logErr("Generating ODoc reference failed: " + result.stderr + result.stdout)
+ exit(1)
+ }
+
# --------------------
- name : Check pom.xml
to :
@@ -165,6 +193,7 @@ todo:
- Prepare ojob saved
- Prepare ojob doc
- Prepare shell complete
+- Generate ODoc reference
- Build OpenAFOS
- Repack OpenAFOS
- Copy OpenAF
diff --git a/buildos.js b/buildos.js
index 2f5ae0c87..7998bab5b 100644
--- a/buildos.js
+++ b/buildos.js
@@ -1,5 +1,6 @@
// Build OpenAF
//
+try {
plugin("ZIP");
ow.loadFormat()
@@ -13,6 +14,25 @@ var OPENAF_SRC = OPENAF_BUILD_HOME + "/src";
var OPENAF_BIN = OPENAF_BUILD_HOME + "/bin";
var OPENAF_JS = OPENAF_BUILD_HOME + "/js";
var JAVAC = "javac";
+
+function runBuildCommand(command, label) {
+ // The bootstrap JAR may predate concurrent stdout/stderr draining in af.sh.
+ // Merge the pipes before reading so verbose compiler failures cannot deadlock it.
+ var commandArguments = new java.util.ArrayList()
+ command.forEach(function(part) { commandArguments.add(String(part)) })
+ var process = new java.lang.ProcessBuilder(commandArguments).redirectErrorStream(true).start()
+ var output, status
+ try {
+ process.getOutputStream().close()
+ output = af.fromBytes2String(process.getInputStream().readAllBytes())
+ status = process.waitFor()
+ } finally {
+ if (process.isAlive()) process.destroyForcibly()
+ process.getInputStream().close()
+ }
+ if (status != 0) throw new Error(label + " failed (exit " + status + "): " + output)
+ if (output.length > 0) log(label + ": " + output)
+}
var smallClassPath = "";
var EXTERNAL = false;
@@ -61,7 +81,7 @@ function buildClasspath() {
if (isUndefined(listfiles)) {
logErr("Didn't found the OPENAF_LIB. Please configure it.");
- java.lang.System.exit(0);
+ throw new Error("OPENAF_LIB is unavailable: " + OPENAF_LIB)
}
for (var i in $from( listfiles.files ).sort("filename").select() ) {
@@ -108,7 +128,7 @@ function buildSource() {
excludeFilter = "plugins/Wedo";
var arrayList = listFiles(OPENAF_SRC, new RegExp(".+\.java$"), excludeFilter);
log("Found #" + arrayList.length + " java sources.");
- sourcePath = arrayList.join(" ");
+ sourcePath = arrayList;
return sourcePath;
}
@@ -155,13 +175,13 @@ io.writeFileString(OPENAF_BUILD_HOME + "/js/openaf.js", jsOpenAF);
io.rm(OPENAF_BIN);
io.mkdir(OPENAF_BIN);
-var cmd = JAVAC + " -cp " + classpath + " -encoding UTF-8 -source 21 -target 21 -Xlint:deprecation -d " + OPENAF_BIN + " " + buildSource();
+var cmd = [JAVAC, "-cp", classpath, "-encoding", "UTF-8", "-source", "21", "-target", "21", "-Xlint:deprecation", "-d", OPENAF_BIN].concat(buildSource())
log("Compiling...");
-log(af.sh(cmd, "", undefined, true));
-if (__exitcode != 0) {
- logErr("Error compiling: " + __stderr);
-}
-$sh(JAVAC + " -source 21 -target 21 -d " + OPENAF_BIN + " " + OPENAF_SRC + "/openaf/Launcher.java").exec();
+runBuildCommand(cmd, "Java compilation")
+runBuildCommand([JAVAC, "-source", "21", "-target", "21", "-d", OPENAF_BIN, OPENAF_SRC + "/openaf/Launcher.java"], "Launcher compilation")
+;["openaf/AFCmdOS.class", "openaf/Launcher.class", "openaf/CompileJS2Java.class"].forEach(function(name) {
+ if (!io.fileExists(OPENAF_BIN + "/" + name)) throw new Error("Missing compiled class: " + name)
+})
var tempJar = new ZIP(io.readFileBytes(OPENAF_BUILD_HOME + "/jar-in-jar-loader.zip"));
var binFiles = listFiles(OPENAF_BIN, new RegExp("\.class$"));
@@ -255,12 +275,13 @@ if (io.fileExists(ojson)) {
var compileJS2Java = (classfile, script, path) => {
var tmpFile = io.createTempFile("build_", ".js");
- io.writeFileString(tmpFile, script);
-
- var cmd = ow.format.getJavaHome() + "/bin/java -classpath " + OPENAF_BUILD_HOME + "/bin:" + OPENAF_BUILD_HOME + "/lib/js.jar openaf.CompileJS2Java " + classfile + " " + tmpFile + " " + path;
- $sh(cmd)
- .prefix(classfile)
- .get(0)
+ try {
+ io.writeFileString(tmpFile, script)
+ runBuildCommand([ow.format.getJavaHome() + "/bin/java", "-classpath", OPENAF_BIN + PATHSEPARATOR + OPENAF_LIB + "/js.jar", "openaf.CompileJS2Java", classfile, tmpFile, path], classfile)
+ if (!io.fileExists(path + "/" + classfile + ".class")) throw new Error("Missing compiled script: " + classfile)
+ } finally {
+ io.rm(tmpFile)
+ }
}
var addCompiledClasses = (baseName) => {
@@ -275,6 +296,7 @@ var addCompiledClasses = (baseName) => {
}
}
+var compileErrors = new java.util.concurrent.ConcurrentLinkedQueue()
//for(i in jsList) {
parallel4Array(jsList, function (i) {
try {
@@ -315,20 +337,16 @@ try {
if (doIt) {
log("-> Compiling " + file.filename);
- var output = af.sh("java " + javaUnsafeFlag + "-jar " + OPENAF_BUILD_HOME + "/compiler.jar --language_out " + "ECMASCRIPT_2019" + " --env CUSTOM --strict_mode_input false --rewrite_polyfills false --js " + OPENAF_BUILD_HOME + "/js/" + file.filename + " --js_output_file " + OPENAF_BUILD_HOME + "/jsmin/" + file.filename, "", null, false);
+ var compilerCommand = [ow.format.getJavaHome() + "/bin/java"]
+ if (javaUnsafeFlag.trim().length > 0) compilerCommand.push(javaUnsafeFlag.trim())
+ runBuildCommand(compilerCommand.concat(["-jar", OPENAF_BUILD_HOME + "/compiler.jar", "--language_out", "ECMASCRIPT_2019", "--env", "CUSTOM", "--strict_mode_input", "false", "--rewrite_polyfills", "false", "--js", OPENAF_BUILD_HOME + "/js/" + file.filename, "--js_output_file", OPENAF_BUILD_HOME + "/jsmin/" + file.filename]), file.filename + " minification")
log("<- Compiled " + file.filename);
destjssha.files.push({
file: file.filename,
orig: sha1(io.readFileStream(OPENAF_BUILD_HOME + "/js/" + file.filename)),
dest: sha1(io.readFileStream(OPENAF_BUILD_HOME + "/jsmin/" + file.filename))
});
- if (output.length > 0) log(file.filename + ": " + output);
- if (__stderr.length > 0) {
- if (__stderr.match(/ WARNING - /))
- logWarn(file.filename + ": " + __stderr);
- else
- logErr(file.filename + ": " + __stderr);
- }
+
} try {
log("Compiling from minimized " + file.filename + "...");
if (validationForCompile(file.filename))
@@ -338,7 +356,7 @@ try {
//af.compileToClasses(file.filename.replace(/\./g, "_"), "var __" + file.filename.replace(/\./g, "_") + " = function(require, exports, module) {" + io.readFileString(OPENAF_BUILD_HOME + "/jsmin/" + file.filename) + "}", OPENAF_BUILD_HOME + "/jslib");
compileJS2Java(file.filename.replace(/\./g, "_"), "var __" + file.filename.replace(/\./g, "_") + " = function(require, exports, module) {" + io.readFileString(OPENAF_BUILD_HOME + "/jsmin/" + file.filename) + "}", OPENAF_BUILD_HOME + "/jslib");
} catch(e) {
- logErr("Error while compiling to java classes ('" + file.filename + "'): " + e);
+ throw new Error("Error while compiling to java classes ('" + file.filename + "'): " + e)
}
sync(function () {
tempJar.putFile("js/" + file.filename, io.readFileBytes(OPENAF_BUILD_HOME + "/jsmin/" + file.filename));
@@ -354,7 +372,7 @@ try {
//af.compileToClasses(file.filename.replace(/\./g, "_"), "var __" + file.filename.replace(/\./g, "_") + " = function(require, exports, module) {" + io.readFileString(OPENAF_BUILD_HOME + "/js/" + file.filename) + "}", OPENAF_BUILD_HOME + "/jslib");
compileJS2Java(file.filename.replace(/\./g, "_"), "var __" + file.filename.replace(/\./g, "_") + " = function(require, exports, module) {" + io.readFileString(OPENAF_BUILD_HOME + "/js/" + file.filename) + "}", OPENAF_BUILD_HOME + "/jslib")
} catch(e) {
- logErr("Error while compiling to java classes ('" + file.filename + "'): " + e);
+ throw new Error("Error while compiling to java classes ('" + file.filename + "'): " + e)
}
sync(function () {
tempJar.putFile("js/" + file.filename, io.readFileBytes(OPENAF_BUILD_HOME + "/js/" + file.filename));
@@ -363,9 +381,12 @@ try {
}
}
return i;
-} catch(e) { }
+} catch(e) {
+ compileErrors.add(i.filename + ": " + e)
+}
return true;
});
+if (!compileErrors.isEmpty()) throw new Error("JavaScript compilation failed: " + compileErrors.toString())
tempJar.putFile("compiledJS.jar", zipJSlib.generate({"compressionLevel": 9}));
zipJSlib.close();
@@ -437,10 +458,15 @@ try {
"scopesigil": OPENAF_BUILD_HOME + "/js/openafsigil.js",
"index": OPENAF_BUILD_HOME + "/js/example.js"
};
- saveHelp(OPENAF_BUILD_HOME, helpFiles);
+ loadHelp()
+ var helpGen = new ODocsGen(helpFiles)
+ // Keep lazy reporter documentation in the existing ow.test help subject.
+ helpGen.odoc["ow.test"].addAll(helpGen.genODoc(OPENAF_BUILD_HOME + "/js/owrap.test.report.js").getAll())
+ var helpDocs = helpGen.getODoc()
+ new ODocs(OPENAF_BUILD_HOME + "/", helpDocs).save()
log("Generating oDoc for Web");
io.mkdir(OPENAF_BUILD_HOME + "/odocweb");
- saveHelpWeb(OPENAF_BUILD_HOME + "/odocweb", helpFiles);
+ new ODocs(OPENAF_BUILD_HOME + "/odocweb", helpDocs).saveWeb()
tempJar.putFile(".odoc.db", io.readFileBytes(OPENAF_BUILD_HOME + "/.odoc.db"));
} catch (e) {
logErr(e);
@@ -462,8 +488,30 @@ log("Building dependencies");
io.writeFileString(OPENAF_BUILD_HOME + "/dependencies.json", stringify(buildDeps()));
log("Creating the openaf.jar in " + OPENAF_BUILD_HOME);
-io.rm(OPENAF_BUILD_HOME + "/openaf.jar");
-tempJar.generate2File(OPENAF_BUILD_HOME + "/openaf.jar", { compressionLevel: 9 }, true);
-tempJar.close();
+var jarTarget = new java.io.File(OPENAF_BUILD_HOME + "/openaf.jar").getCanonicalFile().toPath()
+var jarCandidate = jarTarget.resolveSibling(".openaf-build-" + genUUID() + ".jar")
+try {
+ tempJar.generate2File(String(jarCandidate), { compressionLevel: 9 }, true)
+ tempJar.close()
+ var builtJar = new java.util.jar.JarFile(jarCandidate.toFile())
+ try {
+ ;["openaf/AFCmdOS.class", "openaf/Launcher.class", "compiledJS.jar", "META-INF/MANIFEST.MF"].forEach(function(name) {
+ if (isNull(builtJar.getEntry(name))) throw new Error("Missing JAR entry: " + name)
+ })
+ } finally {
+ builtJar.close()
+ }
+ if (java.nio.file.Files.exists(jarTarget) && java.nio.file.Files.getFileStore(jarTarget).supportsFileAttributeView("posix")) {
+ java.nio.file.Files.setPosixFilePermissions(jarCandidate, java.nio.file.Files.getPosixFilePermissions(jarTarget))
+ }
+ // The candidate is on the same filesystem; a failed atomic replacement leaves the old JAR intact.
+ java.nio.file.Files.move(jarCandidate, jarTarget, java.nio.file.StandardCopyOption.ATOMIC_MOVE, java.nio.file.StandardCopyOption.REPLACE_EXISTING)
+} finally {
+ java.nio.file.Files.deleteIfExists(jarCandidate)
+}
log("Done build");
+} catch (e) {
+ logErr("Build failed: " + e)
+ exit(1)
+}
diff --git a/clean.yaml b/clean.yaml
index 3efd6a240..3b62e888b 100644
--- a/clean.yaml
+++ b/clean.yaml
@@ -43,6 +43,7 @@ jobs:
// Explicit names keep test sources, fixtures and benchmark baselines intact.
var outputs = [
"autoTestAll.results.json", "autoTestAllResults.xml", "autoTestAll.md",
+ "framework-results.json", ".openaf_precompiled",
"results.svg", "asserts.svg", "languages-results.json", "data-file.json",
"autoTestAll.test", "autoTestAll.txt", "autoTestAll.xml", "autoTestAll.xlsx",
"autoTestAll.gz", "autoTestAll.jar", "autoTestAll.zip",
@@ -53,8 +54,10 @@ jobs:
"server.pid", "test_checkin.pid"
].map(function(name) { return "tests/" + name; });
io.listFiles(root + "/tests").files.forEach(function(file) {
- // The DB persistence test uses a timestamp followed by .test.
- if (/^\d{14}\.test(?:\.(?:mv\.db|trace\.db|lock\.db))?$/.test(file.filename)) {
+ // The DB test's day-of-year date format produces 14 or 15 digits.
+ var dbOutput = /^\d{14,15}\.test(?:\.(?:mv\.db|trace\.db|lock\.db))?$/.test(file.filename)
+ var mcpOutput = /^ojob_mcp_tpldesc_[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\.yaml$/i.test(file.filename)
+ if (file.isFile && (dbOutput || mcpOutput)) {
outputs.push("tests/" + file.filename);
}
});
@@ -68,3 +71,19 @@ jobs:
print((dryrun ? "Would remove " : "Removing ") + name);
if (!dryrun && !io.rm(target)) throw "Could not remove " + target;
});
+ // Remove these leftover directories only when empty, without following links.
+ var emptyDirectories = {}
+ ;["tests/private/tmp", "tests/private"].forEach(function(name) {
+ var target = root + "/" + name
+ var directory = new java.io.File(target)
+ if (!directory.isDirectory() || String(directory.getCanonicalPath()).replace(/\\/g, "/") !== target) return
+ var children = directory.list()
+ if (children === null) throw "Could not list " + target
+ for (var i = 0; i < children.length; i++) {
+ if (!emptyDirectories[name + "/" + children[i]]) return
+ }
+ print((dryrun ? "Would remove " : "Removing ") + name)
+ // File.delete is nonrecursive and fails if new contents appeared meanwhile.
+ if (!dryrun && !directory.delete()) throw "Could not remove empty directory " + target
+ emptyDirectories[name] = true
+ })
diff --git a/complete/completion_oafp.sh b/complete/completion_oafp.sh
index 3d05fbdc3..333327573 100644
--- a/complete/completion_oafp.sh
+++ b/complete/completion_oafp.sh
@@ -228,6 +228,11 @@ F_in__in_httpd_inhttpdkeypass_=1
F_in__in_ini=0
F_in__in_javas=0
F_in__in_javas_javasinception_=1
+F_in__in_hprof=0
+F_in__in_jcmd=0
+F_in__in_javadiag=0
+F_in__in_javastacks=0
+F_in__in_javaoom=0
F_in__in_javagc=0
F_in__in_javagc_javagcjoin_=1
F_in__in_javathread=0
@@ -291,6 +296,7 @@ F_in__in_ndslon=0
F_in__in_ndslon_ndslonjoin_=1
F_in__in_ndslon_ndslonfilter_=1
F_in__in_oaf=0
+F_in__in_files=0
F_in__in_oafp=0
F_in__in_oafp_inoafpseq_=1
F_in__in_ojob=0
@@ -413,6 +419,7 @@ F_regression__regressionpath_=0
F_regression__regressionx_=0
F_regression__regressionoptions_=0
F_regression__regressionforecast_=0
+F_removedupsmem_=1
F_removedups_=1
F_removeempty_=1
F_removenulls_=1
@@ -666,6 +673,26 @@ F_secKey__secPass_=0
F_secKey__secMainPass_=0
F_secKey__secFile_=0
F_secKey__secEnv_=0
+F_javapid_=1
+F_javadiagop_=1
+F_javaoptions_=1
+F_javafile_=1
+F_jcmdcommand_=1
+F_hprofmode_=1
+F_hprofindex_=1
+F_hprofid_=1
+F_javareport_=1
+F_javareportkind_=1
+F_javareportformat_=1
+F_javatop_=1
+F_javabundledir_=1
+F_loopcount_=1
+F_loopduration_=1
+F_counterdelta_=1
+F_inparams_=1
+F_filesin_=1
+F_filesworkers_=1
+F_filessource_=1
# Iterate over the arguments
FFOUND=0
@@ -908,6 +935,11 @@ if [ $# -gt 0 ]; then
if [ "$arg" = "in=ini" ]; then FFOUND=1; F_in__in_ini=1; F_in_=0; fi
if [ "$arg" = "in=javas" ]; then FFOUND=1; F_in__in_javas=1; F_in_=0; fi
if [ "${arg#javasinception=}" != "$arg" ]; then FFOUND=1; F_in__in_javas_javasinception_=0; fi
+ if [ "$arg" = "in=hprof" ]; then FFOUND=1; F_in__in_hprof=1; F_in_=0; fi
+ if [ "$arg" = "in=jcmd" ]; then FFOUND=1; F_in__in_jcmd=1; F_in_=0; fi
+ if [ "$arg" = "in=javadiag" ]; then FFOUND=1; F_in__in_javadiag=1; F_in_=0; fi
+ if [ "$arg" = "in=javastacks" ]; then FFOUND=1; F_in__in_javastacks=1; F_in_=0; fi
+ if [ "$arg" = "in=javaoom" ]; then FFOUND=1; F_in__in_javaoom=1; F_in_=0; fi
if [ "$arg" = "in=javagc" ]; then FFOUND=1; F_in__in_javagc=1; F_in_=0; fi
if [ "${arg#javagcjoin=}" != "$arg" ]; then FFOUND=1; F_in__in_javagc_javagcjoin_=0; fi
if [ "$arg" = "in=javathread" ]; then FFOUND=1; F_in__in_javathread=1; F_in_=0; fi
@@ -971,6 +1003,7 @@ if [ $# -gt 0 ]; then
if [ "${arg#ndslonjoin=}" != "$arg" ]; then FFOUND=1; F_in__in_ndslon_ndslonjoin_=0; fi
if [ "${arg#ndslonfilter=}" != "$arg" ]; then FFOUND=1; F_in__in_ndslon_ndslonfilter_=0; fi
if [ "$arg" = "in=oaf" ]; then FFOUND=1; F_in__in_oaf=1; F_in_=0; fi
+ if [ "$arg" = "in=files" ]; then FFOUND=1; F_in__in_files=1; F_in_=0; fi
if [ "$arg" = "in=oafp" ]; then FFOUND=1; F_in__in_oafp=1; F_in_=0; fi
if [ "${arg#inoafpseq=}" != "$arg" ]; then FFOUND=1; F_in__in_oafp_inoafpseq_=0; fi
if [ "$arg" = "in=ojob" ]; then FFOUND=1; F_in__in_ojob=1; F_in_=0; fi
@@ -1156,6 +1189,8 @@ if [ $# -gt 0 ]; then
if [ "$arg" = "regressionx=" ]; then FFOUND=1; F_regression__regressionx_=1; F_regression_=0; fi
if [ "$arg" = "regressionoptions=" ]; then FFOUND=1; F_regression__regressionoptions_=1; F_regression_=0; fi
if [ "$arg" = "regressionforecast=" ]; then FFOUND=1; F_regression__regressionforecast_=1; F_regression_=0; fi
+ # removedupsmem= single option
+ if [ "$arg" = "removedupsmem=" ]; then FFOUND=1; F_removedupsmem_=0; fi
# removedups= single option
if [ "$arg" = "removedups=" ]; then FFOUND=1; F_removedups_=0; fi
# removeempty= single option
@@ -1630,6 +1665,46 @@ if [ $# -gt 0 ]; then
if [ "$arg" = "secMainPass=" ]; then FFOUND=1; F_secKey__secMainPass_=1; F_secKey_=0; fi
if [ "$arg" = "secFile=" ]; then FFOUND=1; F_secKey__secFile_=1; F_secKey_=0; fi
if [ "$arg" = "secEnv=" ]; then FFOUND=1; F_secKey__secEnv_=1; F_secKey_=0; fi
+ # javapid= single option
+ if [ "$arg" = "javapid=" ]; then FFOUND=1; F_javapid_=0; fi
+ # javadiagop= single option
+ if [ "$arg" = "javadiagop=" ]; then FFOUND=1; F_javadiagop_=0; fi
+ # javaoptions= single option
+ if [ "$arg" = "javaoptions=" ]; then FFOUND=1; F_javaoptions_=0; fi
+ # javafile= single option
+ if [ "$arg" = "javafile=" ]; then FFOUND=1; F_javafile_=0; fi
+ # jcmdcommand= single option
+ if [ "$arg" = "jcmdcommand=" ]; then FFOUND=1; F_jcmdcommand_=0; fi
+ # hprofmode= single option
+ if [ "$arg" = "hprofmode=" ]; then FFOUND=1; F_hprofmode_=0; fi
+ # hprofindex= single option
+ if [ "$arg" = "hprofindex=" ]; then FFOUND=1; F_hprofindex_=0; fi
+ # hprofid= single option
+ if [ "$arg" = "hprofid=" ]; then FFOUND=1; F_hprofid_=0; fi
+ # javareport= single option
+ if [ "$arg" = "javareport=" ]; then FFOUND=1; F_javareport_=0; fi
+ # javareportkind= single option
+ if [ "$arg" = "javareportkind=" ]; then FFOUND=1; F_javareportkind_=0; fi
+ # javareportformat= single option
+ if [ "$arg" = "javareportformat=" ]; then FFOUND=1; F_javareportformat_=0; fi
+ # javatop= single option
+ if [ "$arg" = "javatop=" ]; then FFOUND=1; F_javatop_=0; fi
+ # javabundledir= single option
+ if [ "$arg" = "javabundledir=" ]; then FFOUND=1; F_javabundledir_=0; fi
+ # loopcount= single option
+ if [ "$arg" = "loopcount=" ]; then FFOUND=1; F_loopcount_=0; fi
+ # loopduration= single option
+ if [ "$arg" = "loopduration=" ]; then FFOUND=1; F_loopduration_=0; fi
+ # counterdelta= single option
+ if [ "$arg" = "counterdelta=" ]; then FFOUND=1; F_counterdelta_=0; fi
+ # inparams= single option
+ if [ "$arg" = "inparams=" ]; then FFOUND=1; F_inparams_=0; fi
+ # filesin= single option
+ if [ "$arg" = "filesin=" ]; then FFOUND=1; F_filesin_=0; fi
+ # filesworkers= single option
+ if [ "$arg" = "filesworkers=" ]; then FFOUND=1; F_filesworkers_=0; fi
+ # filessource= single option
+ if [ "$arg" = "filessource=" ]; then FFOUND=1; F_filessource_=0; fi
done
fi
@@ -1684,7 +1759,7 @@ if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_out_ -eq 1 ]; then
printf '%s\t%s\n' 'out=dsv' 'A delimiter-separated values format with configurable separator, quoting and headers (for lists or maps; see DSV output options)'
printf '%s\t%s\n' 'out=envs' 'Tries to output the input data as OS environment variables setting commands'
printf '%s\t%s\n' 'out=gb64json' 'Equivalent to out=base64 and base64gzip=true'
- printf '%s\t%s\n' 'out=grid' 'A multiple output ascii grid (useful together with '\''loop'\'')'
+ printf '%s\t%s\n' 'out=grid' 'A multi-widget terminal dashboard (charts, bars, sparklines, heatmaps, bullets, status matrices, timelines, tables, ...) laid out as a grid (useful together with '\''loop'\'')'
printf '%s\t%s\n' 'out=html' 'An HTML format'
printf '%s\t%s\n' 'out=http' 'Sends the output as the body of an HTTP request (POST, PUT, PATCH or DELETE)'
printf '%s\t%s\n' 'out=httpd' 'Serves the output over a local HTTP server (e.g. a live JSON endpoint or an OpenMetrics exporter with loop)'
@@ -1851,7 +1926,7 @@ if [ $F_out__out_envs -eq 1 ]; then
fi
if [ $F_out__out_grid -eq 1 ]; then
if [ $F_out__out_grid_grid_ -eq 1 ]; then
- printf '%s\t%s\n' 'grid=' 'A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see column cell options below).'
+ printf '%s\t%s\n' 'grid=' 'A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see cell fields below).'
fi
fi
if [ $F_out__out_html -eq 1 ]; then
@@ -2091,6 +2166,11 @@ if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_in_ -eq 1 ]; then
printf '%s\t%s\n' 'in=httpd' 'Receives the input from an HTTP request sent to a temporary local HTTP server (e.g. a webhook)'
printf '%s\t%s\n' 'in=ini' 'INI/Properties format'
printf '%s\t%s\n' 'in=javas' 'Tries to list java processes running locally (javasinception=true to include itself). Adds the hsperf file path when the process id matches ow.java.getLocalJavaPIDs()'
+ printf '%s\t%s\n' 'in=hprof' 'Streaming HotSpot heap records; hprofmode=summary returns histogram metadata'
+ printf '%s\t%s\n' 'in=jcmd' 'Explicit JVM diagnostic command with javapid and jcmdcommand'
+ printf '%s\t%s\n' 'in=javadiag' 'Java capabilities, snapshots and explicit capture operations'
+ printf '%s\t%s\n' 'in=javastacks' 'Full text or JSON thread dumps'
+ printf '%s\t%s\n' 'in=javaoom' 'OOM messages and bounded surrounding log excerpts'
printf '%s\t%s\n' 'in=javagc' 'The Java GC log lines text format'
printf '%s\t%s\n' 'in=javathread' 'The Java Thread stack dump lines text format'
printf '%s\t%s\n' 'in=jfr' 'The Java Flight Recorder format'
@@ -2111,6 +2191,7 @@ if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_in_ -eq 1 ]; then
printf '%s\t%s\n' 'in=ndjson' 'A NDJSON (new-line delimited JSON) format'
printf '%s\t%s\n' 'in=ndslon' 'A NDSLON (new-line delimited SLON) format'
printf '%s\t%s\n' 'in=oaf' 'Takes an OpenAF scripting code or OpenAF scripting file to execute and use the result as input'
+ printf '%s\t%s\n' 'in=files' 'Processes a newline-separated list of local filepaths concurrently; see Parallel file lists'
printf '%s\t%s\n' 'in=oafp' 'Takes a JSON/SLON/YAML map input as parameters for calling a sub oafp process (arrays will call multiple oafp processes; inoafpseq=true will process sequentially)'
printf '%s\t%s\n' 'in=ojob' 'Takes a JSON/SLON/YAML map input with a '\''ojob'\'' string and a '\''args'\'' map parameter'
printf '%s\t%s\n' 'in=openmetrics' 'An OpenMetrics/Prometheus compatible format'
@@ -2637,7 +2718,7 @@ if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F__v -eq 1 ]; then
fi
# Print completion for debug=
if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_debug_ -eq 1 ]; then
- printf '%s\t%s\n' 'debug=' 'If true prints debugging messages'
+ printf '%s\t%s\n' 'debug=' 'If true prints debugging messages and enables error stack traces (OAF_ERRSTACK)'
fi
# Print completion for arraytomap=
if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_arraytomap_ -eq 1 ]; then
@@ -2788,6 +2869,10 @@ if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_regression_ -eq 1 ]; then
printf '%s\t%s\n' 'regressionoptions=' 'A JSON/SLON configuration with order (defaults to 2) and/or precision (defaults to 5)'
printf '%s\t%s\n' 'regressionforecast=' 'Optional path to an array of x values for which to forecast the corresponding y'
fi
+# Print completion for removedupsmem=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_removedupsmem_ -eq 1 ]; then
+ printf '%s\t%s\n' 'removedupsmem=' 'Streaming dedup memory budget as a percentage of JVM max heap (default 5, range 0–100). Zero uses a temporary disk index immediately.'
+fi
# Print completion for removedups=
if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_removedups_ -eq 1 ]; then
printf '%s\t%s\n' 'removedups=' 'Removes duplicate array entries, retaining the first occurrence. Map key order is ignored recursively; array order and the distinction between arrays and maps are preserved.'
@@ -3489,7 +3574,7 @@ if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_jwtalg_ -eq 1 ]; then
fi
# Print completion for grid=
if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_grid_ -eq 1 ]; then
- printf '%s\t%s\n' 'grid=' 'A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see column cell options below).'
+ printf '%s\t%s\n' 'grid=' 'A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see cell fields below).'
fi
# Print completion for httpdport=
if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_httpdport_ -eq 1 ]; then
@@ -3733,6 +3818,86 @@ if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_secKey_ -eq 1 ]; then
printf '%s\t%s\n' 'secFile=' 'Optional sBucket file source'
printf '%s\t%s\n' 'secEnv=' 'A boolean flag to use environment variables as sBuckets'
fi
+# Print completion for javapid=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javapid_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javapid=' 'Explicit positive PID or self (collector JVM).'
+fi
+# Print completion for javadiagop=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javadiagop_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javadiagop=' 'capabilities, snapshot (default), histogram, threads, nmt, heapdump, jfr, bundle.'
+fi
+# Print completion for javaoptions=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javaoptions_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javaoptions=' 'OpenAF diagnostic/parser options; also accepts a JSON/SLON string.'
+fi
+# Print completion for javafile=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javafile_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javafile=' 'Explicit target-filesystem destination for heapdump.'
+fi
+# Print completion for jcmdcommand=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_jcmdcommand_ -eq 1 ]; then
+ printf '%s\t%s\n' 'jcmdcommand=' 'One explicit diagnostic command; out=jcmd accepts the input string.'
+fi
+# Print completion for hprofmode=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_hprofmode_ -eq 1 ]; then
+ printf '%s\t%s\n' 'hprofmode=' 'records (default), summary, index, object, find, refs or path. records/summary/index require file.'
+fi
+# Print completion for hprofindex=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_hprofindex_ -eq 1 ]; then
+ printf '%s\t%s\n' 'hprofindex=' 'New directory for index mode; existing disk-backed HPROF index directory for queries.'
+fi
+# Print completion for hprofid=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_hprofid_ -eq 1 ]; then
+ printf '%s\t%s\n' 'hprofid=' 'Hexadecimal object ID for object, refs and path modes.'
+fi
+# Print completion for javareport=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javareport_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javareport=' 'Transform supplied evidence into a structured report.'
+fi
+# Print completion for javareportkind=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javareportkind_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javareportkind=' 'Report label: gc, oom, profile, all (default).'
+fi
+# Print completion for javareportformat=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javareportformat_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javareportformat=' 'out=javareport renders Markdown by default; json selects JSON.'
+fi
+# Print completion for javatop=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javatop_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javatop=' 'Maximum classes, stack groups and event examples; default 50.'
+fi
+# Print completion for javabundledir=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_javabundledir_ -eq 1 ]; then
+ printf '%s\t%s\n' 'javabundledir=' 'out=javabundle creates a new local directory; in=javadiag javadiagop=bundle reopens it.'
+fi
+# Print completion for loopcount=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_loopcount_ -eq 1 ]; then
+ printf '%s\t%s\n' 'loopcount=' 'Positive integer maximum loop passes.'
+fi
+# Print completion for loopduration=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_loopduration_ -eq 1 ]; then
+ printf '%s\t%s\n' 'loopduration=' 'Positive maximum elapsed seconds; does not interrupt an active pass.'
+fi
+# Print completion for counterdelta=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_counterdelta_ -eq 1 ]; then
+ printf '%s\t%s\n' 'counterdelta=' 'Transform options: identity, timestamp and counters (array of dotted paths).'
+fi
+# Print completion for inparams=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_inparams_ -eq 1 ]; then
+ printf '%s\t%s\n' 'inparams=' 'Resolve supported input parameters from one request map; explicit invocation values win. Defaults to false.'
+fi
+# Print completion for filesin=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_filesin_ -eq 1 ]; then
+ printf '%s\t%s\n' 'filesin=' 'Input format for each listed file; defaults to extension detection'
+fi
+# Print completion for filesworkers=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_filesworkers_ -eq 1 ]; then
+ printf '%s\t%s\n' 'filesworkers=' 'Positive worker count; defaults to at most four cores'
+fi
+# Print completion for filessource=
+if [ $_G_EXACT_CHOSEN -eq 0 ] && [ $F_filessource_ -eq 1 ]; then
+ printf '%s\t%s\n' 'filessource=' 'Optional literal field containing the listed filepath'
+fi
# end
if [ $FFOUND -eq 0 ]; then
diff --git a/complete/completion_oafp.yaml b/complete/completion_oafp.yaml
index 3c750f3b7..f8e21927b 100644
--- a/complete/completion_oafp.yaml
+++ b/complete/completion_oafp.yaml
@@ -143,10 +143,10 @@ complete:
- name: out=gb64json
desc: Equivalent to out=base64 and base64gzip=true
- name: out=grid
- desc: A multiple output ascii grid (useful together with 'loop')
+ desc: A multi-widget terminal dashboard (charts, bars, sparklines, heatmaps, bullets, status matrices, timelines, tables, ...) laid out as a grid (useful together with 'loop')
opts:
- name: grid=
- desc: A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see column cell options below).
+ desc: A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see cell fields below).
- name: out=html
desc: An HTML format
opts:
@@ -506,6 +506,16 @@ complete:
opts:
- name: javasinception=
desc: If true includes oafp itself in the local Java process list
+ - name: in=hprof
+ desc: Streaming HotSpot heap records; hprofmode=summary returns histogram metadata
+ - name: in=jcmd
+ desc: Explicit JVM diagnostic command with javapid and jcmdcommand
+ - name: in=javadiag
+ desc: Java capabilities, snapshots and explicit capture operations
+ - name: in=javastacks
+ desc: Full text or JSON thread dumps
+ - name: in=javaoom
+ desc: OOM messages and bounded surrounding log excerpts
- name: in=javagc
desc: The Java GC log lines text format
opts:
@@ -647,6 +657,8 @@ complete:
desc: If true each line is interpreted as an array before filters execute (this allows to filter slon records on a ndslon)
- name: in=oaf
desc: Takes an OpenAF scripting code or OpenAF scripting file to execute and use the result as input
+ - name: in=files
+ desc: Processes a newline-separated list of local filepaths concurrently; see Parallel file lists
- name: in=oafp
desc: Takes a JSON/SLON/YAML map input as parameters for calling a sub oafp process (arrays will call multiple oafp processes; inoafpseq=true will process sequentially)
opts:
@@ -791,7 +803,7 @@ complete:
- name: '-v'
desc: Changes the input to a map with the tool's version info
- name: debug=
- desc: If true prints debugging messages
+ desc: If true prints debugging messages and enables error stack traces (OAF_ERRSTACK)
- name: arraytomap=
desc: If true will try to convert the input array to a map (see arraytomapkey, arraytomapkeepkey)
- name: arraytomapkeepkey=
@@ -903,6 +915,8 @@ complete:
desc: A JSON/SLON configuration with order (defaults to 2) and/or precision (defaults to 5)
- name: regressionforecast=
desc: Optional path to an array of x values for which to forecast the corresponding y
+- name: removedupsmem=
+ desc: Streaming dedup memory budget as a percentage of JVM max heap (default 5, range 0–100). Zero uses a temporary disk index immediately.
- name: removedups=
desc: Removes duplicate array entries, retaining the first occurrence. Map key order is ignored recursively; array order and the distinction between arrays and maps are preserved.
- name: removeempty=
@@ -1269,7 +1283,7 @@ complete:
- name: jwtalg=
desc: Specifies the algorithm used to sign the JWT (HS* or RSA by default). Depends on available algorithms on the current JVM.
- name: grid=
- desc: A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see column cell options below).
+ desc: A JSON/SLON configuration structured as an array of row arrays. Each row array contains one map per column cell (see cell fields below).
- name: httpdport=
desc: The port to listen on (if not provided a free port is chosen and reported on stderr)
- name: httpdhost=
@@ -1415,3 +1429,43 @@ complete:
desc: Optional sBucket file source
- name: secEnv=
desc: A boolean flag to use environment variables as sBuckets
+- name: javapid=
+ desc: Explicit positive PID or self (collector JVM).
+- name: javadiagop=
+ desc: capabilities, snapshot (default), histogram, threads, nmt, heapdump, jfr, bundle.
+- name: javaoptions=
+ desc: OpenAF diagnostic/parser options; also accepts a JSON/SLON string.
+- name: javafile=
+ desc: Explicit target-filesystem destination for heapdump.
+- name: jcmdcommand=
+ desc: One explicit diagnostic command; out=jcmd accepts the input string.
+- name: hprofmode=
+ desc: records (default), summary, index, object, find, refs or path. records/summary/index require file.
+- name: hprofindex=
+ desc: New directory for index mode; existing disk-backed HPROF index directory for queries.
+- name: hprofid=
+ desc: Hexadecimal object ID for object, refs and path modes.
+- name: javareport=
+ desc: Transform supplied evidence into a structured report.
+- name: javareportkind=
+ desc: 'Report label: gc, oom, profile, all (default).'
+- name: javareportformat=
+ desc: out=javareport renders Markdown by default; json selects JSON.
+- name: javatop=
+ desc: Maximum classes, stack groups and event examples; default 50.
+- name: javabundledir=
+ desc: out=javabundle creates a new local directory; in=javadiag javadiagop=bundle reopens it.
+- name: loopcount=
+ desc: Positive integer maximum loop passes.
+- name: loopduration=
+ desc: Positive maximum elapsed seconds; does not interrupt an active pass.
+- name: counterdelta=
+ desc: 'Transform options: identity, timestamp and counters (array of dotted paths).'
+- name: inparams=
+ desc: Resolve supported input parameters from one request map; explicit invocation values win. Defaults to false.
+- name: filesin=
+ desc: Input format for each listed file; defaults to extension detection
+- name: filesworkers=
+ desc: Positive worker count; defaults to at most four cores
+- name: filessource=
+ desc: Optional literal field containing the listed filepath
diff --git a/docs/OJOB-INTERACT.md b/docs/OJOB-INTERACT.md
new file mode 100644
index 000000000..5bbcfb8b8
--- /dev/null
+++ b/docs/OJOB-INTERACT.md
@@ -0,0 +1,98 @@
+# Event-driven interaction jobs
+
+`ojob interact` keeps a console, TUI or JavaFX view open while existing jobs handle
+user input and timer events. See [the complete example](../examples/ojob-interact.yaml).
+From the repository root, build with `ojob build.yaml`, then run:
+
+```sh
+java -jar openaf.jar --ojob -e "examples/ojob-interact.yaml mode=tui"
+```
+
+Choose `mode=console` for line input or `mode=javafx` for a graphical window.
+Use a build containing this feature; JavaFX additionally requires `plugin-DesktopJavaFX`.
+
+```yaml
+include:
+- ojob.yaml
+todo:
+- (interact):
+ mode: console
+ view:
+ items:
+ - { id: go, type: button, label: Run }
+ state: { count: 0 }
+ bindings:
+ action:go: Work
+ reducer: Update
+jobs:
+- name: Work
+ exec: args.message = "Finished"
+- name: Update
+ exec: |
+ if (args.error) args.state.error = args.error
+ else args.state.count++
+ args.close = true
+```
+
+Options: `mode` defaults to `console`; `title`, `view`, `state`, `bindings`,
+`reducer`, `concurrency` (default 4) and `interval` (milliseconds, optional).
+Bindings use `init`, `action:`, `change:` and `timer`. A binding is a job
+name or `{job: name, args: {...}}`. Initialization finishes before timers start.
+
+Handlers receive independent `event`, `values` and `state` snapshots, plus binding
+arguments. Their changed arguments become `result` for the reducer. Reducers run
+serially and receive **current** `state`, the original `event`, `result` or `error`.
+Set `args.state`, optionally `args.view` and `args.close`. A new view replaces the
+whole view, including field values; retain desired field values in state.
+Uncaught handler failures reach the reducer; a job's explicit catch policy remains
+in effect. Reducer failures terminate the session after draining handlers.
+
+At most `concurrency` handlers run together. Actions received at capacity are
+rejected; changes coalesce per field and timer ticks coalesce. A timer binding has
+at most one invocation running. Events for replaced views are discarded. This
+coordinates returned state, not external side effects or global variables inside jobs.
+
+Console mode presents numbered controls and accepts completed lines. Timer and
+reducer processing continues during input; view output waits for the next prompt.
+If a view changes during input, that answer is discarded and the new menu is shown.
+Use `q`, EOF or Ctrl-C at the main action prompt to close; cancelling a field selection returns to the action prompt. TUI uses the existing terminal provider and JavaFX
+uses the optional graphical provider. Neither provider is selected implicitly.
+
+Closing stops event acceptance and timers, closes the display and drains running
+handlers and their reducers. The embedded job returns `{state, outcome}` in
+`args.interaction`. Jobs should return results instead of printing while the UI is
+active: process-wide output is not captured. Cooperative or forced cancellation is
+not provided.
+
+`ow.screen.interact(options)` is also callable directly. `consoleUI` may supply a
+borrowed `askConsole`-compatible object (`read`, `write`, `raw`) for custom input
+or deterministic testing; it is never closed by the session.
+
+For a borrowed TUI terminal, provide `terminalUI` with the `askConsole` contract,
+including `ansi`, `size` and `altScreen`. The provider restores its terminal state
+and leaves the borrowed terminal open.
+
+Console text and password fields use `ask`, and select/checkbox fields use
+`askChoose`. ANSI terminals retain the normal arrow-key selection; plain terminals
+use numbered choices. Password fields pass `"*"` as the mask rather than echoing
+input. Native text prompts keep JLine cursor editing, history and completion.
+
+The prompt helpers accept an optional final options map. For example:
+
+```javascript
+var ui = askConsole()
+try {
+ var options = { onIdle: function() { processPendingEvents(); return !finished }, pollInterval: 50 }
+ var name = ask("Name: ", __, ui, true, ui.write, options)
+ var choice = askChoose("Action", ["Run", "Close"], __, __, ui, options)
+} finally {
+ ui.close()
+}
+```
+
+`onIdle` runs on the input thread before reads and while waiting, with a default
+poll interval of 50 milliseconds. Return `false` to cancel (`null` for `ask`,
+`undefined` for choice helpers). Exceptions propagate after input cleanup. Keep the
+callback short and avoid starting another prompt or printing over the current one.
+The same options are forwarded by `askEncrypt`, `askDef`, `askN`, `ask1` and
+`askStruct`. Existing calls without options retain their original input behavior.
diff --git a/docs/authoring-testing.md b/docs/authoring-testing.md
index 216f71040..8e5074006 100644
--- a/docs/authoring-testing.md
+++ b/docs/authoring-testing.md
@@ -82,3 +82,7 @@ java -jar openaf.jar -f tests/runOJobCode.js
| Inspecting YAML causes activity | `-compile`, `-jobs`, and related commands load dependencies; plain parsing is a different check. |
For AI-assisted debugging provide the command, version, small input, expected output, and actual diagnostics with secrets removed. Ask for source-backed APIs and a clear distinction between static inspection and execution.
+
+## Sessions and standalone suites
+
+For richer assertions, fixtures, scoped mocks, async tasks and process-isolated workflow verification, see the [ow.test API guide](./ow-test.md). Existing `ow.test.test()` scripts retain their recording behavior. New suite runners return an explicit result and exit code; no oJob orchestrator is required.
diff --git a/docs/channel-graph.md b/docs/channel-graph.md
index 0bb73375b..d89bcf48a 100644
--- a/docs/channel-graph.md
+++ b/docs/channel-graph.md
@@ -274,3 +274,21 @@ Limits to keep in mind:
## Source documentation
The same contracts are documented in the source as Markdown ODoc entries (`ow.ch.types.graph` and `ow.ch.utils.graph`), available with `help ow.ch.types.graph` in the console or `openaf -helpscript ow.ch.types.graph`. See [odoc.md](./odoc.md#opt-in-to-markdown) for the format.
+
+## Evidence and extension metadata
+
+Graph edges preserve nested `props` (including evidence quotes, source revisions,
+locations, extraction methods and confidence) without interpreting wiki semantics.
+The assertion key remains `[from,to,type,provenance,page,section]`.
+
+`ow.ch.utils.graph.metadata(name)` returns a copy of non-entity envelope sections.
+`metadata(name, values)` updates the supplied sections and persists them in both
+JSON-file and channel-backed stores. It rejects read-only writes and replacement
+of `nodes`, `edges` or `_edgeIndex`. This supports independently versioned extraction
+checkpoints without changing envelope version 2.
+
+`neighbors`, `degree`, `traverse` and `path` share `direction`, `type`, `provenance`,
+`evidenceLayer` (string or array), and `minConfidence` filters. `path` also accepts
+`maxDepth`. Legacy edges without evidence/confidence remain navigable when no such
+filters are supplied; they cannot satisfy an evidence or confidence filter. Storage
+never invents verification or performs model extraction.
diff --git a/docs/cli.md b/docs/cli.md
index 9eb48245d..939f146b9 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -60,7 +60,7 @@ With no arguments, OpenAF launches the interactive GUI if a desktop is available
| `--ojob` | – | Execute an oJob (loads the oJob engine). Use with `-e` to pass a YAML file or expression. |
| `--opack` | – | Execute the opack package-manager CLI. Use with `-e` to pass sub-commands. |
| `--py [args...]` | script path and Python arguments | Run a Python script with bridge support and propagate its exit status. All following arguments belong to Python. The legacy `--py -e ` form is retained. |
-| `--oafpy` | – | Emit the `oaf.py` bridge module for use from standalone Python scripts. See [python.md](./python.md). |
+| `--oafpy` | – | Emit the `oaf.py` bridge module, only for scripts run by a standard Python interpreter (`python3 script.py`), not for `pyoaf`/`--py` scripts, which get the callbacks injected. See [python.md](./python.md). |
| `--sb ` | file path | Generate or prepend an OpenAF/oJob/oafp shebang line, chosen by the file's extension. See [Shebang scripts](#shebang-scripts) below. |
| `--bashcompletion ` | arg | Generate bash completion script. |
| `--zshcompletion ` | arg | Generate zsh completion script. |
diff --git a/docs/desktop.md b/docs/desktop.md
index 1ef9da86c..74ed267a4 100644
--- a/docs/desktop.md
+++ b/docs/desktop.md
@@ -191,7 +191,7 @@ without HTTP, JavaFX, a helper process, or extra libraries.
The deliberately small version 1 view is `{version:1, items:[...]}`; version may
be omitted. View-level layout and styling options include `title`, `subtitle`,
`align` (`"left"`, `"center"`, `"right"`), `spacing` (0–8 blank lines between items),
-`padding`, `margin`, `border` (`true`, `"rounded"`, `"single"`, `"double"`, `"heavy"`, `"ascii"`, `"none"`),
+`padding`, `margin`, `border` (`true`, `"rounded"`, `"single"`, `"double"`, `"heavy"`, `"left"`, `"ascii"`, `"none"`),
`borderStyle`, `theme` (`"default"`, `"ocean"`, `"light"`, `"monochrome"`, or a custom theme map),
and `style`.
@@ -201,19 +201,23 @@ characters; reserved prototype identifiers are rejected) and one of:
| Type | Fields | Behavior |
| --- | --- | --- |
| `text` | `text`, optional `title` | Plain text, including newlines; no HTML/ANSI execution |
-| `button` | `label` | Emits `action` when activated |
-| `input` | `label`, `value` (default empty), optional `placeholder` | Single-line text; emits `change` on commit |
+| `button` | `label`, optional `variant` (`"default"`\|`"primary"`\|`"success"`\|`"warning"`\|`"error"`) | Emits `action` when activated |
+| `input` | `label`, `value` (default empty), optional `placeholder`, `password`, `fieldWidth` | Single-line text; emits `change` on commit |
| `select` | `label`, `options`, `value` (default first option) | String choices; emits `change` when selected |
+| `checkbox` | `label`, `value` (`"true"`\|`"false"` or boolean, default `"false"`) | Boolean toggle; emits `change` when toggled |
| `divider` | optional `label`, `char` | Horizontal rule / section divider |
| `spacer` | optional `lines` (1–32, default 1) | Vertical spacing lines |
-| `progress` | `value`, optional `label`, `min`, `max`, `showPercent` | Read-only progress bar |
+| `progress` | `value`, optional `label`, `min`, `max`, `showPercent`, `smooth`, `barStyle` | Read-only smooth progress bar |
+| `table` | `rows` (array of scalar maps), optional `columns`, `title` | Read-only structured data table |
+| `sparkline` | `values` (array of finite numbers), optional `label`, `min`, `max`, `trend` | Read-only inline sparkline |
+| `row` | `items` (1–16 child items), optional `gap` (0–8) | Horizontal multi-column container |
Each item also accepts optional layout and styling properties: `align` (`"left"`, `"center"`, `"right"`),
`style`, `labelStyle`, `focusStyle` (strings such as `"BOLD,ITALIC,UNDERLINE,FG(39)"` or maps with
`fg`, `bg`, `bold`, `italic`, `underline`, `doubleUnderline`, `dim`/`faint`, `strikethrough`, `reverse`/`invert`, `blink`, `hidden`,
supporting named colors, 256-color indices `0..255`, `#rgb`/`#rrggbb` hex, and `rgb(r,g,b)` truecolor),
-`padding`, `margin`, `spacing`, `width`, `border`, `borderStyle`, and `disabled`.
-For standalone terminal styling, UTF-8 alignment, and box drawing, use `ow.loadScreen()` (`ow.screen`).
+`padding`, `margin`, `spacing`, `width`, `span` (1–12 proportional width inside a `row`), `border`, `borderStyle`, `shadow`, and `disabled`.
+For standalone terminal styling, UTF-8 alignment, keybinding bars (`ow.screen.keybar`), and box drawing, use `ow.loadScreen()` (`ow.screen`).
Views contain at most 128 items and 64 KiB of UTF-8 JSON. Text is limited to 8192
characters, labels and select options to 256, input values to 4096. Select options
@@ -223,14 +227,14 @@ TUI additionally strips control codes from displayed labels, titles, and text.
Events use `win.on("message", fn)` and contain
`{message:{type:"action"|"change", payload:{id:"controlId", values:{...}}}}`.
-`values` contains the current values of every input/select. The facade validates
+`values` contains the current values of every input/select/checkbox. The facade validates
IDs, control types, complete value sets, lengths, and select choices before
calling application code. View revisions retire input racing a replacement; stale
input is discarded rather than interpreted against the new controls. Input commits on Enter in TUI and on the browser's
normal change/blur event in GUI. Buttons activate with Enter or mouse click.
`win.setView(nextView)` replaces the entire view asynchronously, including values,
-and resets TUI focus/scroll. `win.send("view", nextView)` is equivalent. Preserve
+while preserving focus, scroll position, and input cursors if the previously focused control `id` still exists in `nextView` (otherwise resetting focus/scroll to the top). `win.send("view", nextView)` is equivalent. Preserve
values from the event snapshot when building a replacement if edits should remain.
No implicit DOM patches or application JavaScript run. Other `send` message types
and a custom `messaging` option are rejected for view windows; HTML windows retain
diff --git a/docs/llm-decisions.md b/docs/llm-decisions.md
index 708322ef7..78e1bfceb 100644
--- a/docs/llm-decisions.md
+++ b/docs/llm-decisions.md
@@ -32,7 +32,7 @@ State is a nonempty text string or a JSON data object/array. Whitespace-only tex
Every question is evaluated against the same supplied state. Decisions ignore stored conversation, `withInstructions`, `withContext`, tools, MCP tools, and callbacks. They neither append history nor run tools. Sequential decisions require explicit separate calls. Structured requests place the question specification in system instructions and state in user data. A returned routing label is data; application code remains responsible for authorization and execution policies.
-Version 1 supports text/JSON and native image input for Ollama and OpenAI. Streaming, tool options, and other unsupported option keys are rejected.
+Version 1 supports text/JSON, native image input for Ollama and OpenAI, and native multimodal input for Gemini. Streaming, tool options, and other unsupported option keys are rejected.
### Image decisions with Ollama
@@ -319,3 +319,30 @@ tool execution use `LLM_DECISION_UNSUPPORTED`; invalid schemas, malformed respon
authentication, and transient failures retain their existing error categories.
After tools execute, callers must never restart the whole invocation through a
fallback API. Successful tool results remain in conversation history on failure.
+
+## Native Gemini decisions
+
+Select `model: "gemini-decision-1"` (or `models/gemini-decision-1`) with `type: "gemini"`. `auto` selects native Decisions for this model; ordinary Gemini models retain structured decisions. Per-call `options.model` is honored. The decision-only model cannot use the structured strategy. Native calls use `POST /decisions` under the configured versioned Gemini URL (default `https://generativelanguage.googleapis.com/v1beta`), retaining configured authentication, headers, and timeout. Endpoint/account availability is unknown until execution.
+
+```javascript
+var ai = $llm({ type: "gemini", key: getEnv("GEMINI_API_KEY"), model: "gemini-decision-1" })
+var result = ai.decide("Evaluate this insurance claim.", {
+ damage: { type: "boolean", instructions: "Does the evidence show physical damage?" }
+}, {
+ requireProbabilities: true,
+ input: [
+ { type: "image", mime_type: "image/jpeg", data: photoBase64, resolution: "low" },
+ { type: "document", mime_type: "application/pdf", uri: uploadedPdfUri }
+ ]
+})
+```
+
+`options.input` is a nonempty ordered array, initially supported only by Gemini native decisions. Required `state` remains text/JSON context, sent as the first text part. Additional text parts use `{ type: "text", text: "..." }`. Media parts use `type: "image"`, `"audio"`, `"video"`, or `"document"`, a matching `mime_type`, and exactly one of raw base64 `data` or an HTTPS/Google Cloud Storage `uri`. Documents currently accept PDF only. Callers read files and manage uploads; the wrapper does not fetch media or accept local paths. Existing `options.images` remains specific to Ollama/OpenAI.
+
+Image/video parts optionally accept `resolution`: `low`, `medium`, `high`, or `ultra_high`. Audio parts optionally accept positive integer `sample_rate` and `channels`. Video processing controls and multimodal question instructions are not exposed. Unknown fields, malformed base64, conflicting sources, and unsupported options fail before HTTP. Google validates actual media contents and URI availability.
+
+Native requests support up to 1,000 questions and 2–255 choice options or score levels. Choice IDs cannot have surrounding whitespace or control characters. OpenAF caps serialized UTF-8 bodies at 64 KiB for text-only calls and 32 MiB when `input` is supplied; these are client limits, not Google's service limits. Native calls reject all structured-generation provider options and do not merge chat `params`.
+
+Boolean questions map to `noul` with optional `false_description`/`true_description` criteria. Returned probabilities and confidence are retained separately; scores expose both the modal level and probability-weighted expectation. Distribution checks use OpenAF's four-decimal tolerance without asserting provider rounding precision. Blocked or malformed results raise typed decision errors. Usage comes from the native `usage` envelope, including zero output tokens when reported. Calls remain stateless with no automatic retry or fallback.
+
+Wire fixtures follow the [official Python SDK v3.2.0](https://github.com/googleapis/python-genai/tree/v3.2.0/google/genai/_gaos/types/decisions). Fixture tests do not establish live provider availability.
diff --git a/docs/llm-frontend-guide.md b/docs/llm-frontend-guide.md
index 864d0ec00..83ab15e9e 100644
--- a/docs/llm-frontend-guide.md
+++ b/docs/llm-frontend-guide.md
@@ -49,7 +49,7 @@ These are the versions currently visible in the repo snapshot:
| --- | --- |
| jQuery | 3.7.1 |
| Materialize | 2.2.2 |
-| Chart.js | 4.5.1 |
+| Chart.js | 4.6.1 |
| Handlebars | 4.7.8 |
Treat these as the baseline for generated offline UIs unless the repo snapshot changes.
diff --git a/docs/llm-tui-guide.md b/docs/llm-tui-guide.md
index 63d2b8b0f..be81914b7 100644
--- a/docs/llm-tui-guide.md
+++ b/docs/llm-tui-guide.md
@@ -99,7 +99,7 @@ All visualization functions accept `palette: "auto"` in `opts` to adapt to the t
| --- | --- |
| `ow.format.viz.live(rendererFn, opts)` | Managed render loop: fps, diff, autoStart, watchResize |
| `ow.format.viz.createCanvas(opts)` | 2-D character drawing buffer (write cells, call render()) |
-| `ow.format.viz.diffFrames(prev, next, opts)` | Terminal patch: only redraw changed lines |
+| `ow.format.viz.diffFrames(prev, next, opts)` | Terminal patch: replace frame and report changed lines |
| `ow.format.viz.watchResize(cb, opts)` | Fire a callback when the terminal is resized |
## Color scheme reference
@@ -334,14 +334,14 @@ function showStatus() {
## Live-updating dashboard pattern
-Use `ow.format.viz.live(rendererFn, opts)` for animated screens. It manages the render loop, handles terminal resize, and applies `diffFrames` to redraw only changed lines.
+Use `ow.format.viz.live(rendererFn, opts)` for animated screens. It manages the render loop, handles terminal resize, and applies `diffFrames` to replace the previous frame.
`live` options:
| Option | Default | Description |
| --- | --- | --- |
| `fps` | `8` | target frames per second |
-| `diff` | `true` | use `diffFrames` for efficient partial redraws |
+| `diff` | `true` | use `diffFrames` for frame replacement |
| `autoStart` | `true` | start immediately |
| `watchResize` | `true` | re-render on terminal resize |
| `onError(e)` | — | error callback |
@@ -472,3 +472,236 @@ if (isDef(asciiMoPath)) {
1. `https://github.com/OpenAF/mini-a/blob/main/mini-a-con.js` — Reference interactive console session
2. `https://github.com/OpenAF/openaf/blob/master/js/owrap.format.js` — Full `ow.format` / `viz` / `term` API
3. `https://github.com/OpenAF/openaf/blob/master/js/openaf.js` — `printTable`, `ansiColor`, `printTree`, `printBars`
+
+### Category distributions: pie, donut and stacked bars
+
+Load `ow.loadFormat()` first. Each renderer returns a string; use `print()` for static
+output or return it from a dashboard renderer. Inputs can be `[50, 30, 20]`, a map
+such as `{ A: 50, B: 30, C: 20 }`, or records with `label`, `value` and optional
+`color`. Values must be finite non-negative numbers; invalid values and colours
+throw. Empty input produces `(empty)` and zero totals produce `(no data)`.
+
+```javascript
+ow.loadFormat()
+var values = [
+ { label: "A", value: 50, color: "BLUE" },
+ { label: "B", value: 30, color: "GREEN" },
+ { label: "C", value: 20, color: "YELLOW" }
+]
+
+// One-line category distribution; disable summary text to devote every cell to the bar.
+print(ow.format.printStackedBar(values, { width: 40, showPercent: false }))
+print(ow.format.printPie(values, { size: "tiny", width: 60 }))
+
+// Small and medium circles. Named sizes describe geometry before external legends.
+print(ow.format.printPie(values, { size: "small", mode: "braille" }))
+print(ow.format.printPie(values, { size: "medium", mode: "halfblock" }))
+print(ow.format.printDonut(values, { size: "small" }))
+print(ow.format.printDonut(values, {
+ size: "medium", innerRadius: 0.6, centerText: "65%", legend: "right"
+}))
+
+// Normalized percentage bar with a separate legend.
+print(ow.format.printStackedBar(values, {
+ width: 40, normalize: true, showPercent: true, legend: "bottom", palette: "auto"
+}))
+print(ow.format.printStackedColumns([
+ { label: "Host 1", values: { CPU: 50, Memory: 30, Other: 20 } },
+ { label: "Host 2", values: { CPU: 20, Memory: 50, Other: 30 } }
+], { width: 30, height: 8 }))
+```
+
+`small` uses 12×5 geometry and `medium` uses 20×8. Explicit `width`/`height`
+constrain the entire output, including legends, and override preset geometry.
+Supplying just one dimension derives the other from `cellAspect` after reserving
+legend space. Dashboard-allocated dimensions remain bounds unless the widget's
+own options explicitly set width or height. `size: "auto"` chooses a fitting
+preset. Below 8×4 geometry, pie/donut fall back to a stacked summary; select
+`fallback: "text"` for text only. `legend` accepts `auto`, `right`, `bottom`,
+`inline` and `none`; a constrained right legend moves below the chart when needed.
+Centre text never overwrites the donut ring. If it cannot fit, it goes to the
+legend; `centerTextOverflow: "clip"` or `"omit"` changes that policy.
+
+`mode: "auto"` prefers coloured half-blocks, with separate upper/lower colours.
+Braille has finer geometry but only one foreground colour per cell: mixed cells
+use the majority category, with input-order ties. Monochrome Braille uses stipples;
+ASCII geometry uses category letters. Half-block monochrome falls back to ASCII.
+`cellAspect` defaults to 0.5 (physical cell width/height); fonts can require adjustment.
+Angles are degrees: `startAngle: -90`, `clockwise: true` starts at the top.
+
+Colour is optional. `palette` accepts `auto`, `none`, `16`, `256`, `truecolor`;
+`colors` supplies category overrides. `color: false` and `NO_COLOR` suppress ANSI.
+Tiny positive slices can have no rendered samples; legends mark them with `*`.
+The default `maxCategories: 12` aggregates excess categories as `Other (n)`;
+use zero to retain all. Percentages describe the data, not quantized pixel areas.
+Duplicate labels remain separate and receive occurrence suffixes.
+
+Compact bars show category IDs and percentages inline; use a bottom legend for full labels.
+Stacked bars use stable largest-remainder allocation. Colour Unicode bars use
+eighth-cell blocks where representable, falling back to whole cells if more than
+two categories share a cell. Monochrome uses category letters. Absolute mode is
+`normalize: false, max: 200`; a maximum below the total throws. Column charts use
+a shared maximum and consistent category identity across columns. A column chart
+too narrow to retain every column throws rather than dropping data.
+
+```javascript
+// Mixed dashboard. Grid cells use obj instead of data and accept the same types/options.
+print(ow.format.printDashboard([[
+ { type: "pie", title: "Distribution", data: values },
+ { type: "donut", title: "Share", data: values,
+ options: { innerRadius: 0.6, centerText: "65%" } },
+ { type: "stackedBar", title: "Resources", data: values,
+ options: { legend: "bottom" } }
+]], { width: 100, height: 12, border: true }))
+
+// Live output: stop the controller when finished.
+var live = ow.format.viz.live(function(ctx) {
+ return ow.format.printDashboard([[
+ { type: "donut", title: "Live share", data: [50 + ctx.frame % 10, 30, 20],
+ options: { size: "auto", legend: "right" } },
+ { type: "stackedBar", title: "Resources", data: values }
+ ]], {
+ width: ctx.size.width, height: Math.max(1, ctx.size.height - 1),
+ capabilities: ctx.capabilities, border: true
+ })
+}, { fps: 4 })
+// live.stop()
+
+// Deterministic no-colour rendering, including redirected stdout:
+print(ow.format.printPie(values, {
+ width: 32, height: 8, palette: "none", unicode: false,
+ capabilities: { width: 32, height: 8, ansi: false, unicode: false, colorMode: "none" }
+}))
+```
+
+Use static rendering when redirecting output to a file, for example save the last
+snippet in `distribution.js` and run `openaf -f distribution.js > distribution.txt`.
+Explicit capabilities and dimensions do not require a TTY. Renderers do not move
+the cursor or perform external I/O. `viz.diffFrames` currently rewrites the frame;
+it detects colour-only changes, clears removed rows and preserves the next frame's
+cursor origin. It is not a per-cell diff engine.
+
+For text composition, use `visibleLength`, `string.ansiClip` and `string.ansiPad`.
+Clipping preserves supported Unicode clusters and complete styling escapes, closes
+ANSI styles/hyperlinks, and respects column budgets. Emoji widths follow OpenAF's
+`VISIBLELENGTH_WIDE_EMOJI` setting; actual terminal fonts can differ. Capability
+width/height overrides apply only to the current call and do not change the cache.
+
+#### Measuring render performance
+
+Use the existing `ow.format.viz.benchmarkRender` after warming up the JVM:
+
+```javascript
+var render = function() {
+ return ow.format.printPie([50, 30, 20], {
+ size: "medium", mode: "braille", palette: "16", legend: "none",
+ capabilities: { width: 80, height: 24, ansi: true, unicode: true, colorMode: "16" }
+ })
+}
+for (var i = 0; i < 100; i++) render()
+for (var batch = 0; batch < 5; batch++) {
+ print(ow.format.viz.benchmarkRender(render, { iterations: 200 }))
+}
+```
+
+Reference budgets after warm-up: p95 at most 5 ms for a 40-column stacked bar,
+15 ms for a medium pie/donut, and 50 ms for a 100×30 mixed dashboard. These are
+measurement targets, not portable unit-test timeouts. Record JVM, hardware and
+background load when comparing results. `viz.live` also accepts an explicit
+`capabilities` map; with it, automatic terminal resize polling is disabled and
+updates use the supplied dimensions.
+
+### Diverging bars, treemaps and sparkline annotations
+
+These additions use the same offline rendering and capability options as pie and
+stacked charts. They return strings, with no printing or cursor movement.
+
+```javascript
+ow.loadFormat()
+print(ow.format.printDivergingBars({ Regression: -12, Unchanged: 0, Improvement: 30 }, {
+ width: 50, symmetric: true, palette: "auto"
+}))
+print(ow.format.printTreemap({ API: 50, Cache: 30, Workers: 20 }, {
+ width: 40, height: 10, legend: "right", palette: "auto"
+}))
+print(ow.format.printSparkline([10, 25, null, 40, 70, 55], {
+ width: 40, min: 0, max: 100, missing: "gap",
+ thresholds: [{ value: 60, color: "RED" }],
+ markMin: true, markMax: true, highlightLast: "YELLOW", trend: true
+}))
+```
+
+Diverging bars accept signed number arrays, category records, or value maps.
+The default symmetric range centres the zero axis; `symmetric: false` allocates
+negative/positive space according to their respective extents. Explicit `min`
+and `max` must include zero and all values. `labels` and `showValue` default to
+true. The default width is 40 and the height is the number of values. Monochrome
+uses minus/plus bars, so direction remains readable without colour. Very narrow
+boxes use signed text. Categories retain their order and are never aggregated.
+
+Treemaps accept the non-negative category formats supported by `printPie`.
+Defaults are 40×10, `labels: true`, `cellAspect: 0.5`, and an automatic bottom
+legend occupying up to three rows. `legend: "right"` reserves a side panel when
+it fits. Balanced recursive slicing splits along the longer physical dimension,
+using stable value order and integer cell boundaries. Categories too small to
+receive cells are marked `*`; a truncated legend announces hidden categories.
+This deliberately favours predictable small layouts over a squarified algorithm.
+Labels never extend beyond their rectangles. Use `legend: "none"` to devote the
+whole box to geometry. Small boxes use a stacked distribution instead.
+
+Sparkline annotations are opt-in. Existing calls retain their glyphs, sampling
+and defaults. Enhanced mode supports:
+
+- `min`/`max`: fixed geometry bounds; values outside the range clamp to the endpoint.
+- `missing: "gap" | "skip" | "error"`: handles null, undefined and NaN. Other
+ nonnumeric or infinite values throw. The default in enhanced mode is `gap`.
+- `markMin`/`markMax`: use ▼/▲, or v/^ in ASCII. Max wins when both markers apply.
+- `highlightLast`: true for yellow, or an explicit colour for the last visible value.
+- `trend`: append ↑/↓/→, or +/-/= in ASCII, comparing first and last finite values.
+- `thresholds: [{value,color}]`: thresholds apply in ascending order.
+- `colorScale`: an array of category colours or `{min,max,colors}`. Explicit scale
+ bounds give multiple series a consistent colour scale. Threshold colours take
+ precedence over the scale; last-value highlighting takes precedence over both.
+
+Enhanced sparklines budget labels, names and annotations inside the requested
+width. Downsampling selects the last point in each bin and retains the last
+sample. No-colour output still includes geometry, extrema markers and trend.
+Both `divergingBars` and `treemap` are dashboard/grid widget types. For example:
+
+```javascript
+print(ow.format.printDashboard([[
+ { type: "divergingBars", title: "Change", data: { A: -10, B: 25 } },
+ { type: "treemap", title: "Capacity", data: { API: 50, Cache: 30, Other: 20 } }
+]], { width: 80, height: 12 }))
+```
+
+Very small positive percentages are displayed as `<0.1%` at the default precision,
+rather than rounded to zero. Aggregated values that overflow a finite JavaScript
+sum are labelled `sum > 1.7976931348623157e+308`; normalized shares remain finite.
+
+The optional benchmark is reproducible without external dependencies:
+
+```sh
+cd tests
+java --enable-native-access=ALL-UNNAMED -jar ../openaf.jar -f benchmark-format-viz.js > /tmp/format-viz-benchmark.json
+```
+
+To exercise real colour modes on POSIX systems, run the command with `env -u NO_COLOR`
+prefixed; this changes only that child process. Otherwise the benchmark correctly
+honours `NO_COLOR` and measures monochrome fallbacks.
+
+It records OS/architecture, JVM, `NO_COLOR` status, warm-up count, five batches of 200 renders,
+legacy baselines, twelve-category alternating-colour input, new renderers and a
+mixed dashboard. Budgets are reported per renderer. Set
+`FORMAT_VIZ_BENCH_ENFORCE=true` to enforce reference-machine budgets; ordinary
+unit tests do not assert wall-clock timings. Sample counts can be overridden with
+`FORMAT_VIZ_BENCH_WARMUP`, `FORMAT_VIZ_BENCH_ITERATIONS` and `FORMAT_VIZ_BENCH_BATCHES`.
+
+The following candidates remain intentionally unimplemented: horizontal range
+charts (highest utility/lowest complexity), percentile strips, grouped bars,
+logarithmic histograms, and waterfalls. Quadrant encoding, public raster/renderer
+registries and per-cell frame diffs also remain outside this implementation.
+
+See the [terminal visualization validation snapshot](openaf-advanced.md#terminal-visualization-validation-snapshot-2026-11-08)
+for the current test matrix, real-colour benchmarks and remaining native-platform
+verification limits.
diff --git a/docs/mcp-client.md b/docs/mcp-client.md
new file mode 100644
index 000000000..60484b359
--- /dev/null
+++ b/docs/mcp-client.md
@@ -0,0 +1,331 @@
+# MCP client capabilities and MCP Apps
+
+`$mcp()` is a synchronous, generic MCP client. It does not implement diagram
+editing, run an LLM, or execute server-provided HTML. This guide accompanies
+[the basic client guide](openaf-advanced.md#20-mcp-client-mcp) and
+[OAuth configuration](mcp-oauth.md).
+
+## Public APIs
+
+Call `initialize()` before discovery, resources or tools; always call `destroy()`
+in `finally`. Initialization returns the client. `getInfo()` returns the server's
+initialization/discovery information; `getCapabilities()` returns a copy of its
+capabilities. `getClientInfo()` includes transport diagnostics, negotiated era,
+HTTP session information and recent notifications. Diagnostics may contain tool
+arguments or resource data; do not publish them indiscriminately.
+
+| API | Behavior |
+| --- | --- |
+| `listTools()`, `listPrompts()` | Collect up to 1000 pages, retaining the first page's metadata and conservative combined cache bounds. A remaining `nextCursor` means enumeration is incomplete. |
+| `callTool(name, arguments, httpOptions)` | Preserves the server result envelope, including unknown fields. Existing HTTP per-call options, blacklist, `preFn` and `posFn` remain supported. |
+| `getPrompt(name, arguments)` | Returns the prompt result unchanged. |
+| `listResources()` | Collects resource pages, including names, descriptions, MIME types and metadata. |
+| `listResourceTemplates()` | Collects `resourceTemplates` pages; URI template expansion is the caller's responsibility. |
+| `readResource(uri)` | Sends an absolute URI unchanged. Returns all `contents`, including `text`, base64 `blob`, MIME types and metadata. Does not read local files or dereference HTTP URLs itself. |
+| `subscribeResource(uri, callback)` | Requires `resources.subscribe`, a dedicated legacy connection, and a working event transport. Callback receives `(params, message)` for resource updates. HTTP starts a GET listener first. |
+| `unsubscribeResource(uri)` | Sends unsubscribe and removes the callback after success. |
+| `onRequest(method, handler)`, `offRequest(method)` | Register/remove a handler receiving `(params, request)`. Return a synchronous result; throw `{code, message, data}` for a JSON-RPC error. No promises. |
+| `onNotification(method, handler)`, `offNotification(method)` | Register/remove one callback per method, receiving `(params, message)`. Re-registration replaces that method's callback. Option `onNotification(message)` remains supported alongside registrations. |
+| `onSamplingRequest(handler)` | Registers `sampling/createMessage` and opts into basic sampling. No implicit LLM invocation; sampling tools/toolChoice are explicitly rejected. |
+| `onElicitationRequest(handler, modes)` | Registers `elicitation/create`. Default modes: `{form:{}}`; opt into `{form:{},url:{}}` only with an appropriate user interface. URL mode requires negotiated version 2025-11-25 or later. |
+| `setRoots(roots)` | Explicit array of `{uri:"file:///...", name:"..."}`. Registers `roots/list`; no filesystem scanning or environment-derived defaults. An empty array shares no roots. Legacy clients notify the server of later changes. |
+| `continueRequest(method, originalParams, inputRequired)` | Explicit modern MRTR continuation. Runs registered handlers, copies opaque `requestState`, and sends keyed `inputResponses` on a new request. One round only; returns any further `input_required` unchanged. |
+| `startListening()`, `stopListening()` | Opt into/close one legacy HTTP GET event stream. A 405 or non-SSE endpoint fails explicitly. No automatic reconnect or event replay. |
+| `cancelRequest(id, reason)` | Sends `notifications/cancelled`; does not guarantee remote cancellation or roll back tool effects. |
+| `exec(method, params, execOptions)` | Low-level RPC. Optional `execOptions.onRequestId(id)` exposes the outgoing id for cancellation. Keep tool permission checks in the caller when using raw methods. |
+| `getToolUI(name)` | Returns a copy of `_meta.ui` or undefined when absent. |
+| `getAppResource(name)` | Resolves a tool's `_meta.ui.resourceUri` through `resources/read`; requires a `ui://` URI. Returns the full resource envelope. |
+| `hasApps()` | Discovers whether any visible tool has UI resource metadata. This is discovery, not a claim that a browser host exists. |
+
+Resource methods require the advertised `resources` capability. Server errors and
+`input_required` results remain observable rather than becoming empty lists.
+Discovery is not cached by this client: a new list call refreshes it. Applications
+that cache results should invalidate their own cache on the appropriate event.
+
+## Transports, protocol versions and lifecycle
+
+The default stays **2025-06-18**. `protocolVersion:"auto"` probes `server/discover`
+for the stateless **2026-07-28** era, then falls back to legacy initialization.
+An explicit `protocolVersion:"2026-07-28"` probes that era and fails if unsupported.
+Legacy negotiation recognizes 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25;
+unrecognized negotiated versions fail explicitly. Modern calls carry per-request
+version, client capabilities and identity. HTTP sends the negotiated protocol
+header, plus `Mcp-Method`/`Mcp-Name` for modern calls. Modern `input_required`
+results remain visible through `isInputRequired(result)` until the caller explicitly
+continues them. Do not indiscriminately retry a tool with side effects.
+
+Stdio maintains independent request IDs and a reader/writer pair. Inbound callbacks
+run on two fixed workers with a 128-message waiting queue, separate from the stdout
+reader; they can make nested synchronous requests. Keep callbacks short and impose
+application deadlines. Arbitrarily deep mutually nested callbacks can exhaust the
+two workers and time out. Excess inbound requests receive an explicit queue-full
+error; notifications may be dropped when saturated. Callback exceptions become
+JSON-RPC errors; notification exceptions are isolated. Malformed stdout lines are
+ignored; debug mode reports them. Stderr is drained independently.
+
+HTTP POST accepts JSON or SSE. Inbound requests on a POST's SSE response receive a
+separate authenticated POST response. Callbacks execute on the stream's reader;
+nested requests use independent HTTP connections. `startListening()` provides an
+optional separate GET stream for unrelated legacy notifications. The listener
+uses the configured timeout and stops on EOF/error; inspect `listenerActive` and
+`listenerError` in `getClientInfo()`, then explicitly restart if appropriate.
+Subscriptions must be re-established by the application after reconnecting.
+`type:"sse"` is an alias for Streamable HTTP with SSE responses; it does **not**
+implement the obsolete 2024 separate SSE endpoint/message-URL transport.
+
+A timed-out stdio request sends best-effort cancellation and throws an explicit
+error. Late replies are discarded. HTTP uses finite read/write/call timeouts;
+applications can send cancellation on another thread when they retain the request
+id. Inbound cancellation/progress/logging events are exposed as notifications;
+callback handlers must implement their own cancellation policy. No tool runs are
+replayed automatically. Session-expiry recovery retries only discovery and resource
+reads, once; mutating tool errors remain visible. `destroy()` closes HTTP listeners,
+terminates legacy HTTP sessions with authenticated DELETE, releases waiters and
+clears callbacks/subscriptions. Existing shared connections retain reference counting;
+use `shared:false` (the default) for callback registration and subscriptions.
+
+Register optional capabilities **before** `initialize()` on legacy connections.
+`sampling`, `elicitation` and `roots` supplied directly in `capabilities` are removed
+unless configured through the implemented convenience APIs. Elicitation capabilities
+are filtered for the offered protocol version, and the removed roots list-change
+capability is omitted from modern requests. Deregistering their
+request handler removes the capability from future requests; a legacy connection
+must be reinitialized to advertise the change. Other extensions can be supplied in
+`capabilities.extensions` only when the application implements them.
+
+Modern `subscriptions/listen`, task execution, SSE resumption/redelivery and a
+browser host are not implemented. Modern subscriptions explicitly fail rather
+than falling back to removed legacy methods. That protocol needs ownership of a
+long-lived POST stream, subscription acknowledgement/IDs and termination distinct
+from an ordinary request's final response. The current synchronous request path
+and separate legacy GET listener do not implement that lifecycle; raw RPC access
+must not be treated as subscription support. Extension parameters and results can
+be accessed using `exec()`, but low-level access is not proof of implementation.
+
+## Events and results
+
+```javascript
+client.onNotification("notifications/tools/list_changed", function(params) {
+ // Invalidate your own catalog cache; retrieve a fresh list when needed.
+})
+client.onNotification("notifications/progress", function(params) {
+ print(params.progress + "/" + params.total)
+})
+client.onNotification("notifications/message", function(params) {
+ // Route server logs according to your application's privacy policy.
+})
+```
+
+The same registration works for prompt/resource list changes, resource updates,
+`notifications/cancelled`, and extension notifications. Progress tokens can be
+supplied through `exec("tools/call", {name, arguments, _meta:{progressToken:...}})`.
+Modern logging requires the per-request `_meta["io.modelcontextprotocol/logLevel"]`.
+
+`callTool()` keeps text, images, audio, resource links, embedded resources,
+`structuredContent` (including non-object JSON values), `isError` and `_meta`.
+No MIME type or binary payload is stripped. `toGptTools()` retains the complete
+input schema and excludes tools whose `_meta.ui.visibility` omits `"model"`.
+Plain text-only results keep the historical text return. Structured, multimedia,
+error, metadata-bearing and continuation results become a JSON serialization of
+the full envelope, suitable for the existing string-based GPT tool interface.
+This preserves data but does not convert media into a provider's native image/audio
+message format; applications can use `callTool()` directly for that conversion.
+
+## Optional MCP Apps web host contract
+
+Core retrieval never evaluates HTML/JavaScript. A web application such as mini-a
+can use `listTools()`, `getToolUI()`, `getAppResource()`, `callTool()` and the event
+APIs as its server-side MCP connection. Only a real host should advertise
+`capabilities.extensions["io.modelcontextprotocol/ui"]` with
+`{mimeTypes:["text/html;profile=mcp-app"]}`.
+
+Use the official [MCP Apps SDK and specification](https://github.com/modelcontextprotocol/ext-apps)
+for the browser side. It defines the JSON-RPC `postMessage` bridge; do not forward
+arbitrary browser messages to `exec()`:
+
+1. Validate the tool and its `ui://` resource URI. Fetch HTML through that same
+ authenticated MCP connection and retain `_meta.ui.csp`, `permissions`, and
+ `domain`. Validate the MIME type `text/html;profile=mcp-app` before rendering.
+2. Host the resource in a sandbox isolated from the parent runtime, preferably a
+ separate origin using the SDK sandbox proxy. Restrict script, resource and
+ connection origins using the resource CSP and the host's own policy. Grant no
+ filesystem, cookies, OAuth credentials or environment access to the iframe.
+3. Validate each `postMessage` source, origin, shape and lifecycle state. With the
+ proxy, await `ui/notifications/sandbox-proxy-ready`, then deliver
+ `ui/notifications/sandbox-resource-ready`. The view initiates `ui/initialize`;
+ respond with the SDK's negotiated version/capabilities/context, then await
+ `ui/notifications/initialized` before sending view notifications.
+4. Deliver `ui/notifications/tool-input` before
+ `ui/notifications/tool-result`. Send complete result envelopes, including
+ structured content and private UI metadata where intended for that view.
+5. Forward app `tools/call` only after permission checks, blacklist enforcement,
+ and discovery that `_meta.ui.visibility` includes `"app"` (default visibility
+ is `["model","app"]`). Never expose an app-only tool to the model. Respect
+ separate permissions for `ui/message`, context updates, external links and
+ other host actions; reject unimplemented bridge methods with JSON-RPC errors.
+6. On view teardown, follow `ui/resource-teardown`, remove message listeners,
+ discard pending requests, and release owned MCP sessions. Keep each user's
+ authenticated MCP connection isolated.
+
+`hasApps()` reports discoverability, not trust. Resource metadata and tool
+annotations are untrusted input. No iframe or browser bridge is enabled by
+`$mcp()` itself. The SDK's example hosts provide a runnable rendering reference;
+`tests/mcp-drawio-live.js` demonstrates the core discovery/resource/tool flow.
+The test-only `tests/fixtures/mcp-app-host.js` demonstrates the specified UI
+handshake, input/result delivery, app tool visibility checks and teardown. It
+is exercised by `testAppsHostContract`; it is not a sandbox or production host.
+
+## draw.io examples
+
+These schemas were checked against actual servers on 2026-11-07. Discover them
+again when upgrading: the official tool server and hosted App use different inputs.
+
+### A and E: official Tool Server, headless Mermaid
+
+Install `@drawio/mcp` separately; Node/npm are optional server dependencies, not
+OpenAF dependencies. Set `DRAWIO_BROWSER:none` on the server, not the client UI.
+
+```javascript
+var client = $mcp({cmd:["npx", "-y", "@drawio/mcp@1.11.0"],
+ envs:{DRAWIO_BROWSER:"none"}})
+try {
+ client.initialize()
+ var tools = client.listTools()
+ if (!isArray(tools.tools)) throw "Discovery failed"
+ client.callTool("get_drawio_reference", {format:"mermaid"})
+ var result = client.callTool("open_drawio_mermaid", {content:"graph TD; A-->B;"})
+ if (result.isError || result.error) throw stringify(result)
+ print(stringify(result)) // A diagram link; no browser launched.
+} finally { client.destroy() }
+```
+
+### B: community file editing without a companion editor
+
+Build the [community server](https://github.com/abossard/drawio-mcp) separately.
+Use an application-owned output path; `create_diagram` must not overwrite a user's
+existing file. Server file permissions remain those of its subprocess.
+
+```javascript
+var client = $mcp({cmd:["node", "/path/to/drawio-mcp/build/index.js"]})
+var file = io.createTempFile("diagram-", ".drawio")
+io.rm(file) // create_diagram expects a new path.
+try {
+ client.initialize()
+ var listed = client.listTools()
+ if (!isArray(listed.tools)) throw "Discovery failed"
+ client.callTool("create_diagram", {filePath:file, pageName:"Flow"})
+ client.callTool("add_node", {filePath:file, id:"a", label:"Start", x:20, y:20})
+ client.callTool("add_node", {filePath:file, id:"b", label:"End", x:220, y:20})
+ client.callTool("add_edge", {filePath:file, sourceId:"a", targetId:"b"})
+ print(stringify(client.callTool("read_diagram", {filePath:file})))
+} finally { client.destroy() }
+```
+
+Check every mutation's `isError`/`error` in production. The optional live runner
+checks these responses, plus update/remove/page/undo/redo operations.
+
+### C: hosted MCP App discovery and retrieval
+
+```javascript
+var client = $mcp({url:"https://mcp.draw.io/mcp"})
+try {
+ client.initialize()
+ var tools = client.listTools()
+ if (!isArray(tools.tools)) throw "Discovery failed"
+ tools.tools.filter(t => isMap(t._meta) && isMap(t._meta.ui)).forEach(function(tool) {
+ var resource = client.getAppResource(tool.name)
+ print(resource.contents.map(c => c.mimeType).join(", "))
+ // Give resource to a separately implemented sandboxed Apps host.
+ })
+ // The App uses `mermaid`, unlike the Tool Server's `content` parameter.
+ var result = client.callTool("create_diagram", {mermaid:"graph TD; A-->B;"})
+ print(stringify(result))
+} finally { client.destroy() }
+```
+
+### D: safe opt-in server requests
+
+```javascript
+var client = $mcp({cmd:["my-mcp-server"]})
+client.setRoots([]) // Share no filesystem roots.
+client.onElicitationRequest(function(params) { return {action:"decline"} })
+client.onSamplingRequest(function(params) {
+ throw {code:-32601, message:"No approved sampling provider configured"}
+})
+try {
+ client.initialize()
+ // Synchronous calls can now service inbound legacy requests.
+ // For modern results: inspect isInputRequired(result), then explicitly call
+ // continueRequest(method, originalParams, result) after application approval.
+} finally { client.destroy() }
+```
+
+## Verification matrix
+
+| Capability | Before | Current implementation and evidence |
+| --- | --- | --- |
+| Stdio / concurrent outbound calls | Implemented | Retained; local concurrent regression and real draw.io processes |
+| HTTP JSON / POST SSE | Implemented | Retained; local SSE request/reply fixture and hosted endpoint |
+| Separate legacy HTTP+SSE message endpoint | Missing | Still unsupported; `sse` means Streamable HTTP |
+| Initialization, auto, auth, pagination | Implemented | Retained; existing MCP/OAuth regressions |
+| Resources/templates | Raw `exec()` only | First-class APIs, pagination and metadata; deterministic fixtures |
+| Resource subscriptions | Missing callbacks | Legacy stdio and HTTP GET; modern `subscriptions/listen` remains unsupported |
+| Notifications and inbound requests | Partial notifications only | Method registrations, bounded stdio dispatch, HTTP POST replies and opt-in GET |
+| Sampling / elicitation / roots | Raw negotiation only | Opt-in handlers, explicit roots, modern MRTR continuation |
+| Structured/multimedia results | `callTool` preserved; GPT flattened | Full envelope preserved; GPT text fallback retains rich data |
+| Apps metadata / UI resources | Metadata through raw lists | Discovery helpers and resource retrieval; no browser execution |
+| Cancellation / timeout | Partial transport timeout | Explicit cancellation API; stdio timeout cancellation and late-response cleanup |
+| Reconnect | Legacy session retry | Read-only retry only; listeners/subscriptions require application recovery |
+| Browser host / tasks / modern subscriptions | Missing | Documented host contract; explicitly outside implemented support |
+
+Live results on 2026-11-07:
+
+| Server | Verified | Environment-dependent scope |
+| --- | --- | --- |
+| Official Tool Server `@drawio/mcp` 1.11.0 | Stdio initialize/discovery; all eight exposed tools; XML/Mermaid/CSV, reference, shape search, list/get/set page; invalid input | Browser disabled with `DRAWIO_BROWSER=none`; no rendering claims |
+| Community `abossard/drawio-mcp` main, server 1.0.0 | Stdio discovery of 21 tools; create/read/add nodes/add edge/update/remove/add page/undo/redo | File fallback verified; VS Code bridge, screenshot, cursor/selection and live editor remain unverified |
+| Hosted `https://mcp.draw.io/mcp`, server 1.6.0 | HTTP initialize/discovery; `create_diagram`, `search_shapes`, `get_drawio_reference` discovered; create called; App HTML resource (636399 characters) with MIME/security metadata retrieved | No iframe rendering or UI interaction verification |
+
+All three negotiated 2025-06-18 when offered the unchanged client default.
+Server versions, tools and resource sizes are snapshots, not permanent guarantees.
+
+Run deterministic tests from `tests/` using
+`java -jar ../openaf.jar --ojob -e autoTestAll.MCP.yaml` (includes advanced and
+OAuth jobs). The advanced stdio peer uses the current OpenAF JAR itself: no Node,
+npm, Python or network download is needed. HTTP fixtures bind loopback.
+
+Optional live tests are excluded from normal CI. Create a JSON config containing
+`[{"name":"official","cmd":["node","/installed/@drawio/mcp/src/index.js"]},
+{"name":"community","cmd":["node","/built/drawio-mcp/build/index.js"]},
+{"name":"app","url":"https://mcp.draw.io/mcp"}]`. Set
+`OPENAF_MCP_LIVE_CONFIG=/path/config.json` and optionally
+`OPENAF_MCP_LIVE_REPORT=/path/report.json`, then run
+`java -jar openaf.jar -f tests/mcp-drawio-live.js`. File edits use temporary paths;
+the runner never installs dependencies or opens browsers.
+
+## Implementation validation (2026-11-07)
+
+The rebuilt and synchronously repacked JAR passed all **48 MCP/OAuth test
+exports**, including the 12 advanced-client groups. Additional checks exercised
+numeric inbound/outbound ID collisions, null handler errors and unsupported
+negotiated versions. Generated ODoc contains all 20 new MCP API entries; the
+Markdown examples compile in OpenAF, and the skill frontmatter/test YAML parse.
+The standard bootstrap `build.yaml` stopped in its existing POM comparison job;
+the core `buildos.js` compilation and packaging succeeded without build-source edits.
+
+The final full suite passed **511/512 tests** (0 skipped). Its one failure is
+`AI::OpenAI jsonSchemaPrompt unsupported provider`: the unchanged AI provider test
+expects `JSON Schema responses not supported by this provider`, but receives
+`Error: LLM_DECISION_INVALID_REQUEST`. No AI implementation or test was changed.
+All MCP jobs passed. The optional live runner passed for all three draw.io servers
+against the same final JAR; browser rendering and companion-editor interaction
+remain outside the verified scope.
+
+## Source references
+
+Reviewed the [current MCP specification](https://modelcontextprotocol.io/specification/2026-07-28),
+[legacy Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports),
+[modern schema/MRTR structures](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts),
+[MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx),
+[official draw.io source](https://github.com/jgraph/drawio-mcp), and
+[community source](https://github.com/abossard/drawio-mcp).
diff --git a/docs/mcp-oauth.md b/docs/mcp-oauth.md
index bd8d2d4c2..8b03f78dc 100644
--- a/docs/mcp-oauth.md
+++ b/docs/mcp-oauth.md
@@ -87,6 +87,96 @@ a new controller refreshes or authenticates again. Cached responses omit provide
fields that are not in the stored credential record. `cancel()` controls callback
login; token HTTP requests are bounded by `tokenTimeoutMs`.
+## Automatic MCP OAuth
+
+For an HTTP MCP server that supports dynamic client registration, only the server
+URL and OAuth type are required. Add a token store to reuse the client registration
+and login across sessions:
+
+```javascript
+var mcp = $mcp({
+ type: "remote",
+ url: "https://mcp.atlassian.com/v2/mcp",
+ auth: {
+ type: "oauth2",
+ tokenStore: { type: "sec", profile: "atlassian" }
+ }
+})
+try {
+ mcp.initialize()
+ print(mcp.listTools())
+} finally {
+ mcp.destroy()
+}
+```
+
+Construction is lazy. `initialize()`, `authenticate()`, or the first authenticated
+request discovers the provider, registers a public client, and opens browser consent
+when login is necessary. The local callback listener is reserved before registration;
+its address and client identity are saved before consent. Tokens are encrypted using
+the existing `$sec` adapter. Without `tokenStore`, the registration lasts only for
+that client instance.
+
+When `clientId` and `grantType` are omitted, OpenAF selects `authorization_code` and
+local callback login. Explicit client IDs retain the existing `client_credentials`
+default. Explicit grant, endpoints, scope, callback, and redirect settings take
+precedence. Automatic mode requests scopes from the server's authentication
+challenge; otherwise it leaves scope to the provider. It never requests every
+advertised permission automatically. The provider still controls consent and access.
+
+Discovery uses an unauthenticated GET to inspect the server's challenge, then
+protected-resource and OAuth/OIDC metadata. It does not execute a tool to discover
+authentication. Missing registration support produces a configuration error requiring
+an explicit client identity. Discovered issuer/resource identities are validated and
+metadata/endpoints require HTTPS, with the documented loopback/`allowHTTP` exceptions.
+
+| Option | Automatic OAuth behavior |
+| --- | --- |
+| `registration` | Omitted enables DCR; `false` disables it. A map accepts `clientName` (default `OpenAF`), `applicationType` (default `native`), `initialAccessToken`, and positive `timeoutMs` (default 60000). |
+| `clientMetadataURL` | User-hosted HTTPS client metadata document. Preferred over DCR when the provider advertises support. OpenAF validates its identity and chooses a compatible registered loopback callback. |
+| `tokenEndpointAuthMethod` | Defaults to `none` for public PKCE clients. `client_secret_basic` and `client_secret_post` request confidential DCR clients and apply to login and refresh. |
+| `redirectURI` | Optional in automatic mode. A generated loopback address is saved with registration and reused. |
+| `interactive: false` | Reuses stored credentials and refreshes tokens; never creates a new client or launches login. |
+
+A user-hosted metadata document must contain its exact HTTPS URL as `client_id`, a
+nonempty `client_name`, and `redirect_uris` containing a usable HTTP loopback URI
+with an explicit port. Only public metadata-document clients are supported:
+
+```json
+{
+ "client_id": "https://example.org/openaf-client.json",
+ "client_name": "OpenAF",
+ "redirect_uris": ["http://127.0.0.1:17879/oauth/callback"],
+ "grant_types": ["authorization_code", "refresh_token"],
+ "response_types": ["code"],
+ "token_endpoint_auth_method": "none"
+}
+```
+
+Configure `auth.clientMetadataURL` with that URL. Hosting and publishing the document
+remain the application's responsibility. Unsupported metadata-document capability
+falls back to DCR; an invalid selected document fails explicitly.
+
+`getAuthStatus()` adds non-secret `clientAvailable` and `registrationMethod`
+(`explicit`, `metadata`, or `dynamic`) fields. Inspection may discover metadata and
+load saved state but never registers a client or starts browser login.
+`clearAuth()` removes login tokens while retaining registration.
+`clearAuth({ registration: true })` also forgets the local registration and generated
+callback. It does not delete the client at the provider.
+
+If the saved callback port is occupied, close the conflicting listener and retry.
+OpenAF does not silently create another client or change its registered callback.
+Registration failures, uncertain POST outcomes, expired client secrets, and storage
+write failures stop authentication. Reset registration explicitly before retrying a
+failed registration. A consent denial or timeout retains a successfully stored client.
+Use a separate token-store profile for each account. Registrations are isolated by
+issuer, resource, profile, and registration configuration; issued secrets are stored
+only in encrypted registration records. Initial registration tokens are not persisted.
+
+The Atlassian URL above is an integration example. Provider policy and consent can
+still reject registration or login; deterministic tests do not establish live account
+access.
+
## Persistent delegated OAuth for `$mcp`
`$mcp` uses the same helper for `auth.callback: true`. Persistence remains opt-in
@@ -157,7 +247,7 @@ This keeps WorkIQ's explicit profile keys usable without silently migrating toke
whose full identity was not recorded.
The versioned encrypted record contains the access token, refresh token, scheme,
-absolute expiry and identity fingerprint. It excludes client secrets, authorization
+absolute expiry and identity fingerprint. For explicitly configured clients it excludes client secrets, authorization
codes and PKCE verifiers. Unknown expiry is stored as `null`: the issuing instance
may keep using that token, but another instance must refresh or authenticate again.
@@ -233,3 +323,12 @@ a particular identity provider's app registration or consent policy.
A single page retains its cache metadata. For multiple pages, `ttlMs` is bounded by the earliest remaining page lifetime; a missing or invalid lifetime prevents caching. Different cache scopes produce a private, non-cacheable aggregate (`ttlMs: 0`). After the existing 1,000-page limit, `nextCursor` remains available to indicate that enumeration is incomplete; it is removed only when enumeration finishes.
An error, `input_required`, or malformed list response is returned unchanged, including when it follows successful pages. Callers must inspect the response before treating it as a list; these responses are not converted to empty or partial success.
+
+## MCP event connections
+
+The [MCP client event APIs](mcp-client.md) use the configured authentication
+provider for inbound HTTP request replies, optional GET listeners and session
+DELETE. Tokens remain in the OpenAF connection; never forward Authorization
+headers or token-store data to an MCP App iframe. Session-expiry recovery retries
+only discovery and resource reads; failed mutating tools are returned to the
+caller without replay. Browser login and MCP Apps rendering are separate flows.
diff --git a/docs/oafp.md b/docs/oafp.md
index 3e631e4e4..60f3440f1 100644
--- a/docs/oafp.md
+++ b/docs/oafp.md
@@ -258,3 +258,18 @@ var result = $oafp(data, {
print(result);
```
+
+### Category widgets in grids
+
+The existing `grid` output can use OpenAF widget types `pie`, `donut`,
+`stackedBar`, `stackedColumns`, `divergingBars` and `treemap`. Cells use `obj` for their data and an
+`options` map for renderer settings. For example, an OpenAF grid cell is:
+
+```javascript
+{ type: "donut", title: "Resources", obj: { CPU: 50, Memory: 30, Other: 20 },
+ options: { size: "auto", palette: "auto", legend: "right" } }
+```
+
+See [terminal category distributions](openaf-advanced.md#category-distributions-pie-donut-and-stacked-bars)
+for input formats and fallbacks. These extend the existing grid widget system;
+there are no additional oafp output formats.
diff --git a/docs/odoc.md b/docs/odoc.md
index d3bcf2c6b..a893f4d2f 100644
--- a/docs/odoc.md
+++ b/docs/odoc.md
@@ -39,7 +39,7 @@ The parser does not create searchable fields for ``, ``, `
@@ -62,7 +62,11 @@ Mark an individual entry with `format="markdown"` or its alias `format="md"`:
*/
````
-Markdown entries preserve ordinary newlines, blank lines, and indentation; trailing backslashes are unnecessary. CDATA allows literal `&` and XML/HTML examples. Without CDATA, the body must remain XML-compatible. Existing unmarked entries retain their original extraction and plain-text display.
+The `` remains an XML element and supplies the searchable signature; Markdown belongs in the body after it. Use blank lines between paragraphs, lists for options, backticks for parameter names and short expressions, and language-labelled fenced blocks for standalone examples. The same comment structure works in Java source.
+
+Markdown entries preserve ordinary newlines, blank lines, and indentation; trailing backslashes are unnecessary. The parser removes the leading comment `*` and one following space, so add indentation after that prefix for nested lists or code. It trims blank lines at the edges of the body.
+
+CDATA is useful for examples containing literal `&`, `<`, or XML/HTML. Without it, escape XML-sensitive characters (for example, `&` and `<`); entities are decoded in the extracted text. CDATA cannot contain its closing delimiter `]]>`. Also avoid a literal `` in the body: the source extractor treats it as the end of the entry, even inside CDATA. A `*/` in an example would end the surrounding JavaScript or Java comment. Rewrite or split such examples to keep the source and ODoc well formed. Existing unmarked entries retain their original extraction and plain-text display.
Generated Markdown entries contain `{ k, t, format: "markdown" }`. `ODoc.add(key, signature, text, "markdown")` (or `"md"`) provides the same opt-in for programmatically created entries. Both aliases normalize to `format: "markdown"`. Local ZIP and web gzip storage retain the format marker.
@@ -78,6 +82,10 @@ if (results.length == 1 && isString(results[0].text)) {
`withMD()` implements OpenAF's supported Markdown subset, rather than full CommonMark.
+### Check an entry
+
+Generate help from the edited source using the commands below, then inspect the raw result of `searchHelp()` for the expected key, `format: "markdown"`, line breaks, and example text. Also check `openaf -helpscript greeting` or console help against a build containing the generated database. Redirected output and browser help show the source, so check an ANSI-capable terminal when assessing rendered formatting. When adding or moving entries between modules, ensure every source file is included in the relevant generated help subject; the [build script](../buildos.js) explicitly merges some lazy-module entries.
+
## Generate local help
Run from the directory containing `greeting.js`:
@@ -91,6 +99,38 @@ The first argument is an **output directory**, not a database filename. Each map
After creating an output directory, `saveHelpWeb("help-web", { greetings: "greeting.js" })` writes subject `.gz` files and `__odockeys.gz`. It does not start a web server. The repository's `odocweb/` directory holds generated data. Publish it through your chosen documentation frontend.
+## Generate a Markdown reference wiki
+
+The standalone [genODocReference.yaml](../genODocReference.yaml) job scans JavaScript and Java source directories recursively and writes a browsable Markdown reference:
+
+```sh
+ojob genODocReference.yaml dirs=js,src output=odoc-reference
+```
+
+Open `odoc-reference/index.md` in a Markdown viewer or browse it in a Git repository. The wiki includes category indexes, breadcrumbs, an alphabetical All APIs index, and one page per lookup key. Categories follow API namespaces: `ow.test.assert` appears under `ow` → `ow.test`. Keys without a namespace, including constructors, appear under Globals. All links between generated pages are relative `.md` links. Stable hashed filenames distinguish case, punctuation, and non-ASCII keys on case-insensitive filesystems.
+
+| Argument | Meaning |
+| --- | --- |
+| `dirs` | Required comma-delimited source directories, relative to the invocation directory. Whitespace around each directory is trimmed; overlapping roots are scanned once. Paths containing commas are unsupported. |
+| `output` | Output directory; defaults to `odoc-reference`. The output subtree is excluded from scanning. |
+| `maxBlockMB` | Maximum size of one ODoc block, in units of 1,048,576 UTF-16 code units; defaults to `8`. Must be greater than zero and at most `1024`. This is a parser limit, not a process memory limit. |
+
+The job uses OpenAF's `ioStreamRead`, file I/O, hashing, temporary-directory cleanup, and oJob facilities. It processes fixed-size source chunks, buffers at most one bounded ODoc block, and spools extracted documentation bodies to temporary disk storage. Heap use grows with API/category metadata and source locations rather than total source size or documentation text. It requires writable temporary space alongside the output directory. Symbolic links are skipped; symbolic-link input roots are refused.
+
+Markdown-marked entries retain their formatting, CDATA, and examples. Legacy entries retain their extracted text and explicit line breaks, escaped for Markdown display. Duplicate keys share a page: distinct signatures, bodies, or formats remain separate sections, while identical entries merge and list all source locations in deterministic order. Source locations identify the opening ODoc tag.
+
+Malformed, oversized, unclosed, or unreadable input is reported with source locations where available. Valid entries are still published, the home page is marked incomplete, and the process exits with status `1`. The `.odoc-reference.json` manifest records counts and completeness; diagnostic details are printed to stderr. Invalid arguments or output conflicts stop publication.
+
+Reruns replace manifest-owned pages and remove stale owned pages while preserving unrelated files. Existing files that conflict with new generated filenames are refused before output changes. Pages are staged before publication and the manifest is written last; publication is not a transaction across all files. An interrupted filesystem operation may require restoring a backup or generating into an empty directory. Keep the manifest with the generated wiki. Do not run concurrent generators against the same output directory.
+
+For a direct Java invocation with arguments, pass the job and arguments together as the `-e` value:
+
+```sh
+java -Xmx256m -jar openaf.jar --ojob -e 'genODocReference.yaml dirs=js,src output=odoc-reference'
+```
+
+Focused tests are in `tests/autoTestAll.ODocReference.yaml`, including a 270 MiB source file scanned in a subprocess with a 256 MiB Java heap.
+
## Library interfaces
Call `loadHelp()` before constructing these objects:
diff --git a/docs/ojob-security.md b/docs/ojob-security.md
index f37f8c9aa..692931ef3 100644
--- a/docs/ojob-security.md
+++ b/docs/ojob-security.md
@@ -129,3 +129,21 @@ OpenAF core can enforce script integrity with `OAF_INTEGRITY` and `OAF_INTEGRITY
---
See also: `openaf-flags.md`, main `ojob.md`.
+
+
+## Remote oJob resource limits
+
+Remote definitions are read from a stream with a decoded byte limit before integrity checks or parsing. Redirect and error bodies are closed without buffering. Domain authorization, same-origin credentials, integrity formats, and single-fetch verification remain unchanged.
+
+Trusted JVM properties configure positive integer limits (invalid settings fail closed):
+
+| Property prefix: `openaf.ojob.` | Default | Scope |
+| --- | --- | --- |
+| `maxRemoteBytes` | 8388608 | One decoded definition |
+| `maxRemoteTotalBytes` | 33554432 | Remote bytes in one load/include graph |
+| `maxRemoteRequests` | 128 | Requests including redirect hops in a graph |
+| `maxLoadFiles` | 256 | Files entered in a graph, including local files |
+| `maxIncludeDepth` | 64 | Nested file loads |
+| `remoteTimeoutMs` | 30000 | One download including redirects |
+
+Budgets are released on success and failure. Independent threads have independent budgets; these are not a process-wide concurrency quota. Direct integrity checks and preview reads receive their own budgets. Local file bytes are not capped by the remote byte limits. Raising settings increases resource exposure.
diff --git a/docs/oom-diagnostics.md b/docs/oom-diagnostics.md
new file mode 100644
index 000000000..186789cf6
--- /dev/null
+++ b/docs/oom-diagnostics.md
@@ -0,0 +1,110 @@
+# OOM diagnostics with OpenAF
+
+Load `ow.loadJava()` before these examples. Always select `"self"` (the JVM executing the script) or the PID of the affected process. A fresh helper's own heap usage does not describe another service.
+
+```javascript
+var snapshot = ow.java.collectOOM("self")
+io.writeFileJSON("oom-baseline.json", snapshot)
+// In the same Linux container and as the target owner:
+var snapshot = ow.java.collectOOM(123)
+```
+
+The lightweight snapshot contains JVM version/flags/heap information, source-labelled sections and individual errors. Self instrumentation includes heap/non-heap pools, buffers, GC counters, class and thread counts. Linux adds process status/limits and memory cgroup v1/v2 files resolved from the target's mount information. Raw cgroup values preserve `max` and exact counters. Missing diagnostics do not silently become helper measurements.
+
+```javascript
+ow.java.diagnosticCapabilities(123)
+ow.java.classHistogram(123) // live objects; may collect and pause
+ow.java.classHistogram(123, { live: false }) // includes unreachable objects
+io.writeFileString("threads.txt", ow.java.threadDump(123))
+ow.java.threadDump(123, { file: "/diagnostics/all-threads.json" }) // supporting JVMs only
+ow.java.nativeMemory(123) // reports disabled NMT; does not enable it
+ow.java.heapDump(123, "/diagnostics/unique.hprof")
+ow.java.heapDump(123, "/diagnostics/unique.hprof.gz", { gzip: true })
+```
+
+Files produced by target commands are in the target filesystem. Heap dumps require absolute, unique paths, available disk space, and may cause substantial pauses. The target rejects existing dump files. Compression and all-thread JSON dumps depend on target support. NMT normally needs startup configuration. Snapshots do not request heap dumps, histograms, GC or JFR recording.
+
+## Runtime compatibility
+
+The new HPROF Java core compiles with `javac --release 8`. Self management works through standard management APIs and optional HotSpot MBeans. Java 8 through Java 27 feature availability is detected rather than inferred from the helper's version. Custom runtime images may omit management or attach modules.
+
+External diagnostics first try the Attach API. A Linux HotSpot fallback uses Java Unix-domain sockets (Java 16+), with no JDK executable dependency. It needs the same user and PID/filesystem namespace, readable proc files, an enabled attach mechanism and `/bin/kill` when initialization is needed. Java 8 reduced runtimes without Attach cannot use this fallback; use self instrumentation or a newer helper in the same container. No native library is bundled.
+
+```javascript
+ow.java.jcmd(123, "GC.heap_info", {
+ transport: "socket", // explicitly exercise the JRE-only route
+ timeoutMs: 30000,
+ maxOutputBytes: 16777216,
+ tmpDir: "/tmp"
+})
+```
+
+Initialization verifies ownership, process identity and a caught SIGQUIT before creating the trigger and signaling once. Set `initialize:false` to require an existing listener. Configure `tmpDir` when the JVM uses a different attach directory. Socket timeouts cover connect/write and idle response time; the Attach API can block. Timeout/output-limit failures do not cancel an operation already executing, and commands are never retried after submission.
+
+## Reading HPROF without a JDK
+
+```javascript
+var summary = ow.java.hprofSummary("unique.hprof.gz")
+print(summary.histogram)
+ow.java.parseHPROF("unique.hprof", function(record) {
+ print(stringify(record))
+}, { type: "instance", className: "my/package/Record", values: true, arrayLimit: 16 })
+```
+
+The reader makes two streaming passes to resolve names and inherited fields, reopening gzip input for the second pass. It retains metadata and per-class counts, not an object graph. `maxMetadata` defaults to one million name/class entries; exceeding it throws. `parseHPROF` requires a callback; return `false` to stop the output pass. Filters are exact `type`, `className` and `objectId` values. Metadata types are `class`, `instance`, `objectArray`, `primitiveArray` and `root`.
+
+IDs are hexadecimal strings; Java long field values are decimal strings. `values:true` exposes instance fields/static fields and bounded array samples; defaults expose metadata only. Strings remain objects/references, not reconstructed application text. Object references are not recursively expanded. `payloadBytes` measures serialized field/array data, excluding object headers/alignment; it is neither retained size nor an exact heap footprint. Root counts do not establish ownership paths. Use a graph analyzer for dominators and retained sizes.
+
+Supports HotSpot HPROF 1.0.1/1.0.2 with 4/8-byte IDs, segmented heaps and gzip. Unknown heap subrecords and malformed/truncated files throw with offsets. Unknown length-delimited top-level records are skipped with bounded warnings. Android-specific formats are outside this first version. Future oafp input can call the callback interface without accumulating all records.
+
+## Focused validation
+
+```sh
+javac --release 8 -d /tmp/oom-tests src/openaf/HPROFReader.java tests/java/HPROFReaderTest.java
+java -cp /tmp/oom-tests HPROFReaderTest
+```
+
+The Java oJob suite includes the self snapshot/thread/target-validation test. Java 8 source compatibility is distinct from execution on an actual Java 8 OpenAF distribution.
+
+## oafp integration
+
+The sibling oafp Java diagnostics guide documents `in=javadiag`, `in=jcmd`, `in=hprof`, full-stack parsing, OOM extraction, local bundles and report outputs. Collection requires an explicit PID; report outputs analyze supplied evidence.
+
+`ow.java.diagnosticResult(target, command, options)` adds timestamp, duration and status around the existing string API. Failures have an unknown target outcome and are never retried. It does not add a hard Attach API deadline.
+
+`parseJFR(file, callback, includeDesc, options)` now accepts `events` (exact event names), `startTime`, `endTime` and `maxEvents`; return false from callback to stop. Filtering occurs before field conversion. Optional virtual-thread methods are guarded. Legacy three-argument calls preserve their behavior.
+
+Linux socket fallback now resolves NSpid and the target temporary directory through `/proc/PID/root` when namespace PIDs differ. Explicit `transport:"nsenter"` accepts `nsenterPath` and an `nsenterHelper` argument array naming a preinstalled modern OpenAF launcher plus `js/java-diagnostic-helper.js` in the target mount namespace. It enters mount/PID namespaces with target UID/GID using existing caller privileges. Helper output and runtime are bounded; terminating the helper does not cancel the target command. No automatic escalation or retries occur. Live container validation remains outstanding.
+
+JFR options additionally include `exactLongs`, `arrayLimit` (256 default), and `maxDepth` (32 default). Depth truncation is represented explicitly. Array output is capped; use a larger explicit limit when complete arrays are needed.
+
+Use `isolated:true` to execute external diagnostic calls in a disposable modern OpenAF worker JVM, with bounded output and timeout. The worker requires a rebuilt runtime containing these APIs; `workerCommand` can explicitly select another OpenAF launcher argument array. A worker deadline does not cancel commands already executing in the target. Do not assume these features are installed from checkout documentation alone.
+
+## Disk-backed object and reference queries
+
+```javascript
+ow.java.hprofIndex("heap.hprof.gz", "/diagnostics/incident-index")
+ow.java.hprofFind("/diagnostics/incident-index", {
+ className: "java/lang/String", stringContains: "__conversations", limit: 20
+})
+ow.java.hprofObject("/diagnostics/incident-index", "0x1234", { arrayOffset: 0, arrayLimit: 32 })
+ow.java.hprofReferences("/diagnostics/incident-index", "0x1234", { direction: "incoming" })
+ow.java.hprofPath("/diagnostics/incident-index", "0x1234", {
+ maxDepth: 64, maxVisited: 100000, maxEdges: 1000000, timeoutMs: 30000
+})
+```
+
+`HPROFIndex` uses the bundled H2 database with an 8 MiB page cache, bounded insert batches and disk-backed sorting/traversal. No full object graph is kept in Java collections. A new directory is required; it holds a decompressed heap copy, its SHA-256 and database. Budget disk for both the dump and database/index work. `maxDumpBytes` defaults to 1 TiB; parser metadata limits remain configurable. Failed builds remain incomplete and are rejected on open. All index contents have the same sensitivity as the original heap. Do not alter the indexed heap copy. This is an offline API; collect remotely through existing SSH/container access, then analyze there or copy the dump first.
+
+Indexing reads complete object arrays independently of `parseHPROF`'s sample limit. Reference edges include instance fields (with declaring classes), static fields, class pointers, superclass, loader, signers, protection domain and constant-pool references. Field shadowing remains distinguishable. Java strings support legacy char arrays and modern compact byte arrays with bounded output. Modern UTF-16 byte order comes from target StringUTF16 metadata or explicit `utf16ByteOrder` (`little`/`big`); unknown layouts are reported, never guessed. `stringLimit` defaults to 4096 UTF-16 code units. `hprofFind` string matching searches this prefix and reports partial/undecodable strings. Exact class-name searches include class records as well as instances. Use `afterId`/`nextCursor` for find pagination and `offset`/`nextOffset` for references.
+
+`hprofPath` finds one shortest root path with a disk-backed queue and visited set. It excludes Reference.referent edges unless `includeWeak:true` is requested. A bounded search reports `truncated` and `limitReached`; a missing path under a limit does not establish unreachability. `timeoutMs` is cooperative between traversal steps, not a hard deadline for individual SQL operations. This is reachability analysis, not a dominator calculation or retained-size measurement. A separate scratch database is removed after traversal. Paths depend on the GC roots and references present in the dump.
+
+The parser's opt-in `values:true` records now also provide `fieldDetails`/`staticDetails` with value types and declaring classes, preserving shadowed fields, plus array `dataOffset` and class references. Existing fields and samples remain available.
+
+```sh
+javac --release 8 -d /tmp/oom-tests src/openaf/HPROFReader.java src/openaf/HPROFIndex.java tests/java/HPROFIndexTest.java
+java -Xmx96m -cp '/tmp/oom-tests:lib/*' HPROFIndexTest
+```
+
+Disk-index queries run in a modern collector: the bundled H2 driver requires Java 11 or later, and this OpenAF distribution requires Java 21 or later. Compiling the parser/index sources with `--release 8` does not make the bundled H2 driver executable on Java 8. Dumps can still come from older supported HotSpot targets.
diff --git a/docs/opacks.md b/docs/opacks.md
index 843ac78bd..a17e9f48e 100644
--- a/docs/opacks.md
+++ b/docs/opacks.md
@@ -121,12 +121,22 @@ Invoke it as `openaf --opack [args...] [options]` (packaged distributions
- `-repo ` — prepend an extra repository to search for this run only.
- `-deps` — automatically install missing dependencies instead of prompting interactively.
- `-useunzip` — accepted for compatibility; extraction uses the same safe internal streaming path.
-- `-noverify` — skip the post-install file-hash verification pass.
-- `-cred ` — HTTP basic-auth credentials for protected repositories/URLs.
+- `-noverify` — explicitly bypass staged file-hash verification for trusted input; file-copy failures still abort.
+- `-cred ` — HTTP basic-auth credentials, bound to the first challenged scheme, host, port and package directory. Other protection spaces use their own stored credentials or prompt separately. Older stored credentials without a scheme must be entered again.
- `-arg ` — passed through to `preinstall`/`postinstall` scripts as `arg`.
- `-justcopy` — copy files without registering in the DB or checking versions (used internally by `oJob-common`'s packaging job, see §5).
- `update` also adds: `-all` (update every installed package), `-noerase` (don't delete the old version's files before installing the new one), `-erasefolder` (do remove the old version's install folder — the "keep folder" behavior is the default).
+### Integrity checks
+
+Installation copies every listed file into a private temporary directory and checks that exact snapshot before either incoming install hook or any destination write. Every non-description payload needs a matching `filesHash` value unless `-noverify` is explicitly used. Missing files, failed reads, missing/malformed hashes and mismatches abort the package without reporting success or registering it. Updates defer erasing the old package until the incoming snapshot passes. JSON/YAML descriptions are written from the parsed manifest used for the operation rather than fetched again.
+
+The package generator now includes nested package-description files in the hash list. Legacy packages missing hashes for nested descriptions or other payloads need a regenerated trusted manifest (or an explicit trusted `-noverify` bypass). Only the root description parsed for the operation is exempt.
+
+Legacy 40-digit SHA-1 values remain accepted, including LF/CRLF text compatibility; bare carriage returns in legacy-hashed text are rejected because they can change code semantics without changing that normalized hash. New manifests can provide raw 64-digit SHA-256 or `sha256:` values, verified against exact bytes. This does not authenticate the publisher or protect an attacker-modified manifest.
+
+Only verified staged files are promoted. Unrelated destination files are retained and affected files are backed up for restoration on promotion/hook failure. Rollback failures are reported; arbitrary hook side effects and interruption are not transactional. Staging needs temporary disk space for the payload and backups. Copy-only installs still verify by default, and `-noverify` remains an explicit integrity bypass. The standalone regression can be run from the checkout root with `java -jar openaf.jar -f tests/opack-integrity.js`.
+
### 3.2 Examples
```bash
diff --git a/docs/openaf-advanced.md b/docs/openaf-advanced.md
index 8416be192..5df3be03f 100644
--- a/docs/openaf-advanced.md
+++ b/docs/openaf-advanced.md
@@ -797,10 +797,24 @@ var client = $mcp({
});
```
+For automatic interactive OAuth, omit `clientId` and `grantType` and configure
+`auth: { type: "oauth2", tokenStore: { type: "sec", profile: "my-account" } }`.
+OpenAF discovers endpoints and required scopes, obtains a client identity through
+metadata documents or dynamic registration, reserves a local callback, and opens
+browser consent. The server must support an available registration mechanism.
+See [automatic MCP OAuth](mcp-oauth.md#automatic-mcp-oauth) for defaults and overrides.
+
OAuth2 token URLs can also be auto-discovered from the MCP server's OAuth 2.0 Protected Resource Metadata when `tokenURL`/`authURL` are omitted.
To retain OAuth credentials across sessions, opt in with `auth.tokenStore: { type: "sec", profile: "alice" }`. The built-in adapter uses an encrypted SBucket and coordinates token refresh across local processes. Custom synchronous stores are also supported. See [persistent OAuth, callback login and token stores](mcp-oauth.md) for configuration, failure behavior and storage limitations.
+### Resources, callbacks and MCP Apps
+
+See [MCP client capabilities](mcp-client.md) for resource/template APIs, subscriptions,
+server-initiated request and notification handlers, sampling/elicitation/roots,
+modern continuations, rich results, the optional Apps host contract, verified
+draw.io examples and the capability matrix. The default version remains 2025-06-18.
+
### Tool blacklist
Prevent specific tools from appearing in `listTools()` or being called via `callTool()`:
@@ -818,3 +832,311 @@ client.initialize();
---
See also: `ojob-security.md`, `openaf-flags.md`, and main references.
+
+### Category distributions: pie, donut and stacked bars
+
+Load `ow.loadFormat()` first. Each renderer returns a string; use `print()` for static
+output or return it from a dashboard renderer. Inputs can be `[50, 30, 20]`, a map
+such as `{ A: 50, B: 30, C: 20 }`, or records with `label`, `value` and optional
+`color`. Values must be finite non-negative numbers; invalid values and colours
+throw. Empty input produces `(empty)` and zero totals produce `(no data)`.
+
+```javascript
+ow.loadFormat()
+var values = [
+ { label: "A", value: 50, color: "BLUE" },
+ { label: "B", value: 30, color: "GREEN" },
+ { label: "C", value: 20, color: "YELLOW" }
+]
+
+// One-line category distribution; disable summary text to devote every cell to the bar.
+print(ow.format.printStackedBar(values, { width: 40, showPercent: false }))
+print(ow.format.printPie(values, { size: "tiny", width: 60 }))
+
+// Small and medium circles. Named sizes describe geometry before external legends.
+print(ow.format.printPie(values, { size: "small", mode: "braille" }))
+print(ow.format.printPie(values, { size: "medium", mode: "halfblock" }))
+print(ow.format.printDonut(values, { size: "small" }))
+print(ow.format.printDonut(values, {
+ size: "medium", innerRadius: 0.6, centerText: "65%", legend: "right"
+}))
+
+// Normalized percentage bar with a separate legend.
+print(ow.format.printStackedBar(values, {
+ width: 40, normalize: true, showPercent: true, legend: "bottom", palette: "auto"
+}))
+print(ow.format.printStackedColumns([
+ { label: "Host 1", values: { CPU: 50, Memory: 30, Other: 20 } },
+ { label: "Host 2", values: { CPU: 20, Memory: 50, Other: 30 } }
+], { width: 30, height: 8 }))
+```
+
+`small` uses 12×5 geometry and `medium` uses 20×8. Explicit `width`/`height`
+constrain the entire output, including legends, and override preset geometry.
+Supplying just one dimension derives the other from `cellAspect` after reserving
+legend space. Dashboard-allocated dimensions remain bounds unless the widget's
+own options explicitly set width or height. `size: "auto"` chooses a fitting
+preset. Below 8×4 geometry, pie/donut fall back to a stacked summary; select
+`fallback: "text"` for text only. `legend` accepts `auto`, `right`, `bottom`,
+`inline` and `none`; a constrained right legend moves below the chart when needed.
+Centre text never overwrites the donut ring. If it cannot fit, it goes to the
+legend; `centerTextOverflow: "clip"` or `"omit"` changes that policy.
+
+`mode: "auto"` prefers coloured half-blocks, with separate upper/lower colours.
+Braille has finer geometry but only one foreground colour per cell: mixed cells
+use the majority category, with input-order ties. Monochrome Braille uses stipples;
+ASCII geometry uses category letters. Half-block monochrome falls back to ASCII.
+`cellAspect` defaults to 0.5 (physical cell width/height); fonts can require adjustment.
+Angles are degrees: `startAngle: -90`, `clockwise: true` starts at the top.
+
+Colour is optional. `palette` accepts `auto`, `none`, `16`, `256`, `truecolor`;
+`colors` supplies category overrides. `color: false` and `NO_COLOR` suppress ANSI.
+Tiny positive slices can have no rendered samples; legends mark them with `*`.
+The default `maxCategories: 12` aggregates excess categories as `Other (n)`;
+use zero to retain all. Percentages describe the data, not quantized pixel areas.
+Duplicate labels remain separate and receive occurrence suffixes.
+
+Compact bars show category IDs and percentages inline; use a bottom legend for full labels.
+Stacked bars use stable largest-remainder allocation. Colour Unicode bars use
+eighth-cell blocks where representable, falling back to whole cells if more than
+two categories share a cell. Monochrome uses category letters. Absolute mode is
+`normalize: false, max: 200`; a maximum below the total throws. Column charts use
+a shared maximum and consistent category identity across columns. A column chart
+too narrow to retain every column throws rather than dropping data.
+
+```javascript
+// Mixed dashboard. Grid cells use obj instead of data and accept the same types/options.
+print(ow.format.printDashboard([[
+ { type: "pie", title: "Distribution", data: values },
+ { type: "donut", title: "Share", data: values,
+ options: { innerRadius: 0.6, centerText: "65%" } },
+ { type: "stackedBar", title: "Resources", data: values,
+ options: { legend: "bottom" } }
+]], { width: 100, height: 12, border: true }))
+
+// Live output: stop the controller when finished.
+var live = ow.format.viz.live(function(ctx) {
+ return ow.format.printDashboard([[
+ { type: "donut", title: "Live share", data: [50 + ctx.frame % 10, 30, 20],
+ options: { size: "auto", legend: "right" } },
+ { type: "stackedBar", title: "Resources", data: values }
+ ]], {
+ width: ctx.size.width, height: Math.max(1, ctx.size.height - 1),
+ capabilities: ctx.capabilities, border: true
+ })
+}, { fps: 4 })
+// live.stop()
+
+// Deterministic no-colour rendering, including redirected stdout:
+print(ow.format.printPie(values, {
+ width: 32, height: 8, palette: "none", unicode: false,
+ capabilities: { width: 32, height: 8, ansi: false, unicode: false, colorMode: "none" }
+}))
+```
+
+Use static rendering when redirecting output to a file, for example save the last
+snippet in `distribution.js` and run `openaf -f distribution.js > distribution.txt`.
+Explicit capabilities and dimensions do not require a TTY. Renderers do not move
+the cursor or perform external I/O. `viz.diffFrames` currently rewrites the frame;
+it detects colour-only changes, clears removed rows and preserves the next frame's
+cursor origin. It is not a per-cell diff engine.
+
+For text composition, use `visibleLength`, `string.ansiClip` and `string.ansiPad`.
+Clipping preserves supported Unicode clusters and complete styling escapes, closes
+ANSI styles/hyperlinks, and respects column budgets. Emoji widths follow OpenAF's
+`VISIBLELENGTH_WIDE_EMOJI` setting; actual terminal fonts can differ. Capability
+width/height overrides apply only to the current call and do not change the cache.
+
+#### Measuring render performance
+
+Use the existing `ow.format.viz.benchmarkRender` after warming up the JVM:
+
+```javascript
+var render = function() {
+ return ow.format.printPie([50, 30, 20], {
+ size: "medium", mode: "braille", palette: "16", legend: "none",
+ capabilities: { width: 80, height: 24, ansi: true, unicode: true, colorMode: "16" }
+ })
+}
+for (var i = 0; i < 100; i++) render()
+for (var batch = 0; batch < 5; batch++) {
+ print(ow.format.viz.benchmarkRender(render, { iterations: 200 }))
+}
+```
+
+Reference budgets after warm-up: p95 at most 5 ms for a 40-column stacked bar,
+15 ms for a medium pie/donut, and 50 ms for a 100×30 mixed dashboard. These are
+measurement targets, not portable unit-test timeouts. Record JVM, hardware and
+background load when comparing results. `viz.live` also accepts an explicit
+`capabilities` map; with it, automatic terminal resize polling is disabled and
+updates use the supplied dimensions.
+
+### Diverging bars, treemaps and sparkline annotations
+
+These additions use the same offline rendering and capability options as pie and
+stacked charts. They return strings, with no printing or cursor movement.
+
+```javascript
+ow.loadFormat()
+print(ow.format.printDivergingBars({ Regression: -12, Unchanged: 0, Improvement: 30 }, {
+ width: 50, symmetric: true, palette: "auto"
+}))
+print(ow.format.printTreemap({ API: 50, Cache: 30, Workers: 20 }, {
+ width: 40, height: 10, legend: "right", palette: "auto"
+}))
+print(ow.format.printSparkline([10, 25, null, 40, 70, 55], {
+ width: 40, min: 0, max: 100, missing: "gap",
+ thresholds: [{ value: 60, color: "RED" }],
+ markMin: true, markMax: true, highlightLast: "YELLOW", trend: true
+}))
+```
+
+Diverging bars accept signed number arrays, category records, or value maps.
+The default symmetric range centres the zero axis; `symmetric: false` allocates
+negative/positive space according to their respective extents. Explicit `min`
+and `max` must include zero and all values. `labels` and `showValue` default to
+true. The default width is 40 and the height is the number of values. Monochrome
+uses minus/plus bars, so direction remains readable without colour. Very narrow
+boxes use signed text. Categories retain their order and are never aggregated.
+
+Treemaps accept the non-negative category formats supported by `printPie`.
+Defaults are 40×10, `labels: true`, `cellAspect: 0.5`, and an automatic bottom
+legend occupying up to three rows. `legend: "right"` reserves a side panel when
+it fits. Balanced recursive slicing splits along the longer physical dimension,
+using stable value order and integer cell boundaries. Categories too small to
+receive cells are marked `*`; a truncated legend announces hidden categories.
+This deliberately favours predictable small layouts over a squarified algorithm.
+Labels never extend beyond their rectangles. Use `legend: "none"` to devote the
+whole box to geometry. Small boxes use a stacked distribution instead.
+
+Sparkline annotations are opt-in. Existing calls retain their glyphs, sampling
+and defaults. Enhanced mode supports:
+
+- `min`/`max`: fixed geometry bounds; values outside the range clamp to the endpoint.
+- `missing: "gap" | "skip" | "error"`: handles null, undefined and NaN. Other
+ nonnumeric or infinite values throw. The default in enhanced mode is `gap`.
+- `markMin`/`markMax`: use ▼/▲, or v/^ in ASCII. Max wins when both markers apply.
+- `highlightLast`: true for yellow, or an explicit colour for the last visible value.
+- `trend`: append ↑/↓/→, or +/-/= in ASCII, comparing first and last finite values.
+- `thresholds: [{value,color}]`: thresholds apply in ascending order.
+- `colorScale`: an array of category colours or `{min,max,colors}`. Explicit scale
+ bounds give multiple series a consistent colour scale. Threshold colours take
+ precedence over the scale; last-value highlighting takes precedence over both.
+
+Enhanced sparklines budget labels, names and annotations inside the requested
+width. Downsampling selects the last point in each bin and retains the last
+sample. No-colour output still includes geometry, extrema markers and trend.
+Both `divergingBars` and `treemap` are dashboard/grid widget types. For example:
+
+```javascript
+print(ow.format.printDashboard([[
+ { type: "divergingBars", title: "Change", data: { A: -10, B: 25 } },
+ { type: "treemap", title: "Capacity", data: { API: 50, Cache: 30, Other: 20 } }
+]], { width: 80, height: 12 }))
+```
+
+Very small positive percentages are displayed as `<0.1%` at the default precision,
+rather than rounded to zero. Aggregated values that overflow a finite JavaScript
+sum are labelled `sum > 1.7976931348623157e+308`; normalized shares remain finite.
+
+The optional benchmark is reproducible without external dependencies:
+
+```sh
+cd tests
+java --enable-native-access=ALL-UNNAMED -jar ../openaf.jar -f benchmark-format-viz.js > /tmp/format-viz-benchmark.json
+```
+
+To exercise real colour modes on POSIX systems, run the command with `env -u NO_COLOR`
+prefixed; this changes only that child process. Otherwise the benchmark correctly
+honours `NO_COLOR` and measures monochrome fallbacks.
+
+It records OS/architecture, JVM, `NO_COLOR` status, warm-up count, five batches of 200 renders,
+legacy baselines, twelve-category alternating-colour input, new renderers and a
+mixed dashboard. Budgets are reported per renderer. Set
+`FORMAT_VIZ_BENCH_ENFORCE=true` to enforce reference-machine budgets; ordinary
+unit tests do not assert wall-clock timings. Sample counts can be overridden with
+`FORMAT_VIZ_BENCH_WARMUP`, `FORMAT_VIZ_BENCH_ITERATIONS` and `FORMAT_VIZ_BENCH_BATCHES`.
+
+The following candidates remain intentionally unimplemented: horizontal range
+charts (highest utility/lowest complexity), percentile strips, grouped bars,
+logarithmic histograms, and waterfalls. Quadrant encoding, public raster/renderer
+registries and per-cell frame diffs also remain outside this implementation.
+
+### Terminal visualization validation snapshot (2026-11-08)
+
+Phases 1–5 are implemented. Phase 6 automated checks are green for the local
+macOS build and the offline Linux minimum-runtime checks below. Native desktop
+and Windows visual verification remain explicitly unverified; this snapshot does
+not certify a Windows terminal or a GUI terminal emulator.
+
+| Gate | Observed result |
+| --- | --- |
+| Build with JDK 27.0.1.0.3 | Passed; compiled/repacked JAR produced |
+| Complete repository suite | 532/532 passed; 17,413 assertions; colour cases enabled |
+| Offline Format exports, macOS arm64 / Java 27 | 76 passed from an unrelated working directory |
+| Focused Linux arm64 / Java 21.0.12 checks | 24 passed, no network, read-only JAR/test mounts |
+| Linux arm64 / Java 25 checks | 24 passed before the final colon-SGR compatibility correction |
+| macOS PTY size checks | Direct input, piped stdin, redirected stdout, resize and stdin preservation passed |
+| Linux Java 21 PTY capabilities | stdout TTY and ANSI detected; xterm-256color profile returned |
+| Packaged public APIs and offline help | Pie, donut, stacked bars/columns, diverging bars and treemap present |
+| Unicode/ANSI regressions | Covered clusters, wide cells, CSI/OSC clipping, retained line breaks, colon SGR in JS and Java |
+| Frame/resize lifecycle | Terminal-state emulator verifies changed FG/BG, removed rows and cursor origin; watcher snapshots reused maps and stops polling |
+| Headless font previews | Menlo, 11×22 cells, Braille supported; light and dark inspected |
+| Optimization visual equivalence | Both font-preview PNGs byte-identical before/after treemap run encoding |
+| Native desktop/Windows matrix | Pending: desktop locked; no Windows terminal available |
+
+All ten benchmark budgets passed on both recorded runtimes. The following are the
+largest p95 measurements among five batches of 200 renders, after 100 warm-ups.
+`NO_COLOR` was absent in both processes; these include real-colour encoding rather
+than accidentally timing monochrome fallbacks.
+
+| Renderer | Reference budget, ms | macOS Java 27, ms | Linux Java 21, ms |
+| --- | ---: | ---: | ---: |
+| `legacySparkline` | 5 | 1 | 2 |
+| `legacyHeatmap` | 15 | 2 | 3 |
+| `stackedBar` | 5 | 3 | 3 |
+| `halfblockPie` | 15 | 9 | 9 |
+| `braillePie` | 15 | 12 | 13 |
+| `donut` | 15 | 8 | 9 |
+| `divergingBars` | 10 | 2 | 2 |
+| `treemap` | 40 | 4 | 4 |
+| `enhancedSparkline` | 5 | 1 | 1 |
+| `mixedDashboard` | 50 | 39 | 38 |
+
+A concurrent-load diagnostic run measured 51 ms p95 for the Linux mixed dashboard;
+the table records the controlled run after the full test suite exited. Timing
+budgets are reference-machine measurements, not guarantees under competing load.
+
+Explicit sizing regressions also verify that a small pie/donut can expand to
+24×12, either dimension derives the other from cell aspect ratio, and dashboard
+bounds preserve presets unless widget options explicitly override dimensions.
+
+The unsupported-provider AI fixture was updated to explicitly remove the two
+structured-output interfaces on its local test instances. Provider names no longer
+imply missing capabilities. The exact unsupported-capability error assertion is
+retained, and no production AI implementation was changed.
+
+Relevant tests live in `tests/autoTestAll.Format.js` and are registered after
+`Format::Load Format` in the paired YAML. They include `testPrintPieDonut`,
+`testPrintStackedDistributions`, `testPrintDivergingBars`, `testPrintTreemap`,
+`testSparklineEnhancements`, `testVizRasterEncoders`, `testVizCanvasUnicode`,
+`testAnsiClipClusters`, `testVizFrameTerminalState`, `testVizWatchResize`, and
+mixed dashboard/grid/live cases. Wall-clock budgets remain in the separate
+`tests/benchmark-format-viz.js` harness, not ordinary unit tests.
+
+To rerun the complete suite against the built JAR:
+
+```sh
+cd tests
+env -u NO_COLOR java --enable-native-access=ALL-UNNAMED -jar ../openaf.jar --ojob -e autoTestAll.yaml
+```
+
+To enforce the recorded benchmark budgets on a reference machine:
+
+```sh
+env -u NO_COLOR FORMAT_VIZ_BENCH_ENFORCE=true java --enable-native-access=ALL-UNNAMED -jar ../openaf.jar -f benchmark-format-viz.js
+```
+
+Native terminal font/raster placement, GUI reflow during resize, and Windows
+console integration still require an available native environment. Headless font
+previews and byte-level assertions do not claim to replace those checks.
diff --git a/docs/ow-test.md b/docs/ow-test.md
new file mode 100644
index 000000000..b2425a879
--- /dev/null
+++ b/docs/ow-test.md
@@ -0,0 +1,122 @@
+# Testing with ow.test
+
+`ow.loadTest()` retains the existing `test`, `testExternally`, `assert`, counters, timers, history and reporting entry points. New assertions, suites, async helpers, mocks and workflow testing load on first use. No external runner or LLM is required.
+
+```javascript
+ow.loadTest();
+var tests = ow.test.createSession({ output: false });
+tests.suite('UserService', function(t) {
+ t.fixture('users', function(c) { return c.channel(); });
+ t.beforeEach(function(c) { c.fixture('users').set('alice', {name: 'Alice'}); });
+ t.test('creates user', function(c) {
+ c.assertEqual(c.fixture('users').get('alice').name, 'Alice');
+ });
+});
+var result = tests.run();
+io.writeFileString('results.xml', tests.report.junit(result));
+exit(result.exitCode);
+```
+
+## Compatibility and results
+
+Legacy `test(name, fn, args)` passes `(setResult, args)` to the callback. A passing test returns the original value, including `undefined`. A failure records `FAIL` and returns `undefined`. Existing `assert` retains `compare()` semantics and string exceptions. Nested legacy failures continue to count independently. New `execute(name, fn, options)` passes an execution context and returns a detached result; a failed nested test fails its modern parent.
+
+`test` accepts an optional fourth argument and `testExternally` an optional fourth argument with `failurePolicy: 'record' | 'throw' | 'failFast'`. The default is `record`. Throwing occurs after recording and cleanup. Fail-fast cancels later scheduling cooperatively; it cannot undo already-running work. `execute` and `run` accept the same policy. Suite runs report `exitCode` 0 (pass), 1 (test failure) or 2 (infrastructure/incomplete run). Call `exit(result.exitCode)` explicitly: OpenAF's script launcher can print an uncaught exception without returning a nonzero process exit code.
+
+`getResults()` returns `{schemaVersion:1, sessionId, records, runs, infrastructureErrors, complete}`. Execution records have IDs, parent IDs, status, assertion count, duration in milliseconds, errors with phases, and an encoded return value. Suite runs contain logical tests with every attempt and a `flaky` flag. Statuses are `PASS`, `FAIL`, `ERROR`, `SKIP`, `TODO`, `TIMEOUT`, `CANCELLED`, `BLOCKED`. Legacy counters count started executions, including retries; suite summaries separately count logical cases, attempts and assertions. A started skipped execution is non-failing in legacy counters; declared skip/TODO cases are not started.
+
+Histories and results are detached snapshots. Reading a report never converts live channel counters to numbers. The default channel remains `__owTest::tests`; session channels are private and created on demand. Channel entries preserve atomic hit/pass/fail counters. The internal session owns authoritative results: externally editing the compatibility channel does not edit execution history. Repeated executions retain separate IDs.
+
+`ow.test.report.json(snapshot)`, `.markdown(snapshot)` and `.junit(snapshot, id, name)` are pure reporters. Legacy `toMarkdown()` / `toJUnitXML(id, name)` report all executions; pass a suite run to `report.junit` to report one testcase per logical test with total attempt time. XML escapes attributes and text and replaces characters forbidden by XML 1.0. Infrastructure failures become error testcases. JUnit consumers differ in handling retry metadata; JSON retains all details.
+
+Result encoding bounds depth, node count, strings and property count. Cycles use reference envelopes, undefined/nonfinite numbers use typed envelopes, and Java objects are represented by class name. Known secret property names are redacted. Arbitrary exception messages, URL query parameters and custom property names can still contain sensitive data: review artifacts before sharing. Encoded values are diagnostic data, not automatically executable replay fixtures.
+
+## Assertions
+
+| API | Semantics |
+|---|---|
+| `assertEqual(actual, expected)` | Strict primitive/reference equality, with `NaN` equal to `NaN` and signed zero equal |
+| `assertNotEqual(actual, expected)` | Negation of that equality |
+| `assertDeepEqual(actual, expected, message, options)` | Bounded recursive structural comparison |
+| `assertMatch(value, regex)` | String match using a fresh regex; preserves caller `lastIndex` |
+| `assertContains(collection, item)` | String substring, structural array member, Map key/Set membership, Java collection member/map key |
+| `assertThrows(fn, matcher)` | Synchronous throw; matches string, regex, or `{name,message,javaClass,predicate}`; accepts thrown undefined/null |
+| `assertSchema(value, schema)` | Isolated draft-aware JSON Schema validation without coercion, default insertion or removal |
+| `assertApprox(actual, expected, tolerance)` | Absolute tolerance number or `{absolute,relative}`; tolerance must be nonnegative |
+| `assertType(value, type)` | JS type, `null`, `array`, `date`, `regexp`, `map`, `set`, or `{javaClass}` |
+
+Structural comparison distinguishes a missing key from an undefined value, null from undefined, and an array hole from an undefined element. JS plain objects compare enumerable own keys independent of order; getters are not invoked, and accessor identities must match. Cycles and alias topology must correspond. Dates compare valid epoch times; invalid dates fail. Regex source and flags must match. ES Map keys and Set members use native membership semantics, not structural key matching. Symbols/nonenumerable properties are outside this comparator's data model.
+
+Java arrays, lists and maps compare structurally with exact runtime class matching; Java map keys retain JVM key semantics. Supported Java scalar wrappers, BigInteger/BigDecimal and date classes use `equals`. Thus BigDecimal scale matters and arbitrary Java numeric values are not silently converted to JS numbers. Unsupported Java classes and custom JS instances require explicit user assertions. Node budgets reject pathological comparisons rather than hanging.
+
+New assertion errors have `name: 'AssertionError'`, code, operator, expected, actual, path and machine-readable differences. `ow.obj.schemaCreate(options)` also exposes independent `inspect`, `schemaCompile`, `schemaValidate`, `schemaAdd`, `schemaRemove` helpers. Global schema registrations/options are unchanged.
+
+## Suites, hooks and resources
+
+Suite builders provide `test`, nested `suite`, `beforeAll`, `afterAll`, `beforeEach`, `afterEach`, `skip`, `todo`, `fixture`, and assertion methods. Hooks receive a context. Setup runs outer-to-inner; teardown runs inner-to-outer in reverse registration order. Teardown errors are aggregated and do not erase the body error. A failing `beforeAll` blocks descendant tests and still runs eligible cleanup.
+
+Tests/suites accept `tags`, `timeout` in milliseconds, and `retries`; tests also accept `skip`/`todo`. `run({tags:['fast'], names:['Suite::case'], workers:4})` filters before hooks and schedules independent top-level suites concurrently. Cases within a top-level suite remain sequential. Reports follow declaration order regardless of completion order. Parallel tests must not mutate shared application globals. Fail-fast under concurrency prevents future starts where observed; already-started suites can finish.
+
+`fixture(name, factory, {scope:'test'|'suite'})` lazily creates a resource. Factories call `c.defer(disposer)` to register cleanup. Suite fixtures may depend only on suite fixtures. Contexts provide `tmpDir()`, `channel()`, `defer()`, `bind(fn)`, `skip(reason)`, `checkCancelled()`, assertion methods and async/mock helpers. Cleanup is LIFO. `bind` propagates context to explicitly owned work; arbitrary Java threads do not inherit it.
+
+Deadlines interrupt cooperative work. If a thread does not stop within the cancellation grace period, the session becomes poisoned, completion is false, and resource cleanup waits for actual termination. A poisoned session cannot be reset or reused. This is detection and containment, not an OS-enforced time limit. Use process workers for work that can block indefinitely. Fixture/setup callbacks without an explicit timeout remain trusted synchronous code.
+
+`runFiles(files, options)` loads sorted modules that export `register(t)` or `test*` functions. Loading modules executes their top-level code. `discover(files, {mode:'manifest'})` reads version-1 JSON manifests without executing source.
+
+## Async work, mocks and profiling
+
+`eventually(probe, {equals, timeout:5000, interval:100, backoff:1, maxInterval:1000})` polls a value; use `predicate` instead of `equals` for custom conditions. Probe exceptions propagate unless an explicit `retryOn(error)` accepts them. The last observation and observation count accompany timeout errors. Polling deadlines cannot interrupt a blocking probe.
+
+`c.spawn(fn)` creates an owned OpenAF `$do` task; execution waits for owned tasks and attempts cancellation before cleanup. `await(task, timeout)` supports OpenAF oPromise and Java Future. Native JS Promise and arbitrary thenables are rejected: their queue semantics are not assumed to match Node or browsers.
+
+```javascript
+tests.execute('payment failure', function(c) {
+ c.mock(service, 'charge', [{returns: 1}, {throws: new Error('Unavailable')}]);
+ c.assertEqual(service.charge(), 1);
+ c.assertThrows(function() { service.charge(); }, 'Unavailable');
+ c.assertCalled(service, 'charge', 2);
+});
+```
+
+Mocks require an active owner and an own writable/configurable JS data method. `spy` calls the original and records arguments/results/errors. Handles expose detached `calls()` and idempotent `restore()`. Replacements support a function or bounded response sequence and optional `match(args)`. Restoration preserves the exact descriptor. A second mock of the same member is rejected; calls from unrelated contexts use the original method. Java-backed members, accessors and prototype/global rewriting are unsupported. Inject JS adapters for Java, JDBC, REST, channels, processes and MCP clients.
+
+`timer(key)` returns an idempotent stop handle; legacy `start(key)`/`stop(key)` use per-thread LIFO frames, so identical nested/concurrent keys are independent. Durations use `nowNano()`; wall timestamps are metadata only. Legacy profile summaries remain integer milliseconds. Missing hits are zero; missing extrema/average/last are undefined. `profile(key, fn)` stops in `finally`. Resetting active profiles/sessions is rejected. Memory profiling samples whole-process heap use without forced GC; it is not per-test allocation accounting or a benchmark.
+
+## Isolated oJob verification
+
+```javascript
+var observed = tests.ojob('orders.yaml', {
+ trusted: true,
+ job: 'ProcessOrder',
+ args: {orderId: 123},
+ mocks: {CheckInventory: {output: {available: true}}},
+ timeout: 30000,
+ expect: {status: 'SUCCESS', jobsExecuted: ['ProcessOrder']}
+});
+```
+
+A fresh JVM receives a versioned JSON request in a private temporary directory, an explicit environment allowlist plus `env`, a heap limit (`memoryMB`, default 256), bounded process output, and a deadline. User startup profiles are suppressed with `openaf.test.worker`. No shell interpolation is used. Temporary worker files are removed. The process runner reports whether descendant tracking was available; platforms can deny that facility, so this is not a sandbox guarantee.
+
+Omit `job` to run the workflow's todo list. Selective job mocks transform definitions before compilation and can specify `output`, `error`, `delayMs`; flat argument maps are also accepted. `from`/`to` composition remains intact. The trace reports actual **scheduled job** starts/ends/errors, scheduler log outcomes and explicit state changes. Composed components are not reported as independently executed jobs: instrumentation that changes their shared lexical scope would be misleading. Failed dependency/scheduler logs affect workflow status. Handled job exceptions count according to the resulting oJob outcome.
+
+`expect` supports status (defaults to SUCCESS), exact observed start order (`jobsExecuted`), forbidden jobs, output, output schema and unhandled job error count. `invariants` are predicates over the result. In concurrent workflows, use predicates for partial-order checks instead of asserting a total order. Output is the last completed job's returned args, excluding internal execution IDs; it can still include oJob's `init` data. Traces have bounded diagnostic snapshots. These checks establish observed behavior only, never universal workflow properties. A result distinguishes live and mixed/mocked execution.
+
+Worker requests must set `trusted:true`. Untrusted generated code needs an externally provisioned OS/container sandbox with filesystem/network policy and enforceable resource limits. No such provider is silently substituted with an ordinary JVM.
+
+## Optional oPacks
+
+The sibling `openaf-opacks` repository contains five dependency-free optional modules:
+
+| oPack | Entry point | Delivered capability |
+|---|---|---|
+| TestProperty | `require('test-property.js').create(session)` | Seeded generators, shrinking, replay, bounded schema subset |
+| TestContracts | `require('test-contracts.js').create(session)` | Explicit mock/replay/live modes, REST and injected JDBC/channel/MCP/process adapters |
+| TestCoverage | `require('test-coverage.js').create()` | Explicit probes/LCOV, job coverage, benchmarks, explicit mutation runner |
+| TestVerify | `require('test-verify.js').create(session)` | Preconditions/postconditions, trace invariants, model tests, bounded exploration, SMT-LIB process adapter and backend interface |
+| TestAgent | `require('test-agent.js').create(session, options)` | Manifest validation, read-only MCP descriptors, external sandbox execution boundary |
+
+Automatic statement/branch instrumentation, JaCoCo orchestration, automatic mutation generation, native Promise queue ownership, Lean proof integration, source-to-test generation and OS sandbox providers are not supplied. These remain feasibility-gated follow-ups in the roadmap. Tests, properties, contracts, bounded models and backend proof artifacts retain distinct evidence labels.
+
+The session snapshot schema is published at [ow-test-results.schema.json](./schemas/ow-test-results.schema.json). Suite summaries include `hookAssertions` in the total assertion count. A session can provide a custom `redact(encodedValue)` function for application-specific artifact filtering; it must be synchronous and return serializable data. Generic Java Future cancellation cannot establish whether its body terminated, so a Future timeout poisons the owning session and retains its resources rather than cleaning them up while unknown work may still use them.
+
+`TestVerify.smt(argv, formula, options)` additionally supports an explicitly installed SMT-LIB command with bounded output and a deadline. It records satisfiable/unsatisfiable/unknown outcomes for the encoded formula, with backend identity, version, formula hash and assumptions. No solver is installed by this API.
diff --git a/docs/plans/ow-test-implementation-status.md b/docs/plans/ow-test-implementation-status.md
new file mode 100644
index 000000000..1a579846c
--- /dev/null
+++ b/docs/plans/ow-test-implementation-status.md
@@ -0,0 +1,77 @@
+# ow.test modernization implementation status
+
+This document tracks the implementation of the [accepted roadmap](./ow-test-modernization.md), authorized across core and optional oPacks on 2026-11-06. It distinguishes delivered behavior from gated follow-ups. The full aspirational roadmap is **not all enabled**. Unsupported execution/instrumentation modes fail explicitly.
+
+## Delivered components
+
+| Phase | Implemented | Placement |
+|---|---|---|
+| 1 — correctness | Owned monotonic timers; per-thread legacy frames; idempotent stops; locked commits; detached histories/results; failure policies; corrected pure XML/Markdown reports; explicit CI completion and exit handling | Core `owrap.test.js`, `owrap.test.report.js`, CI/test orchestrators |
+| 2 — assertions/lifecycle | Rich assertions, cycle-aware JS/Java collection comparison, schema instances, suites/hooks, fixtures, tags/names, skips/TODO, retries/flaky outcomes, hook deadlines, deferred cleanup | Core assertion/run modules; `ow.obj.schemaCreate` |
+| 3 — isolation | Scoped own-method mocks, spies, response sequences, argument predicates, call snapshots, descriptor restoration and ownership enforcement | Core mock module |
+| 4 — oJob | Fresh-JVM worker, explicit trusted boundary, individual jobs/full workflows, pre-compilation definition mocks, scheduled execution/state/log events, expectations and invariants | Core oJob/worker modules and narrow oJob seams; owning `oJob-common/oJobTest.yaml` wrappers |
+| 5 — integrations | Explicit live/mock/replay modes; versioned redacted recordings; REST, injected JDBC/channel/MCP/process adapters; deterministic duplicate/reordered message fixtures | Optional `TestContracts` |
+| 6 — concurrency | Eventually, OpenAF oPromise/Java Future adapters, owned async tasks, explicit context binding, concurrent top-level suites, stable reporting order, cancellation/poisoning | Core async/run modules |
+| 7 — properties | Seeded integer/float/string/array/map/record/JSON generators, bounded schema subset, custom generators, shrinking, fixture replay, distribution counters and budgets | Optional `TestProperty` |
+| 8 — measurement | Explicit line/function/branch probes and LCOV, scheduled-job coverage, separate benchmarks/percentiles/comparison, explicit mutation runner and inconclusive outcomes | Optional `TestCoverage` |
+| 9 — agents/verification | Versioned manifests, read-only MCP descriptors, explicit sandbox-provider boundary, regression fixtures, pre/postconditions, trace invariants, model tests, bounded BFS, SMT-LIB process adapter and proof-backend interface | Optional `TestAgent`, `TestVerify` |
+
+No third-party dependencies, services, runner or LLM were added. Optional code is in the sibling `openaf-opacks` repository, not eagerly loaded into OpenAF. All five new packs have package manifests and local smoke tests. oJob-common changes are in its own repository; the installed copy inside this checkout was not rewritten.
+
+## Validation and practical limits
+
+The independent framework harness checks actual values and process status without relying on ow.test's own pass/fail decisions. It covers legacy return/argument semantics, profiles, histories, rich comparisons, XML parsing, schema isolation, hooks, fixtures, retries, fail-fast, concurrent completion, mocks, async ownership, cooperative/noncooperative deadlines, deferred cleanup, worker results and published result schemas.
+
+The full repository orchestrator completed **507 executions: 506 passed, 1 failed, 12,953 assertions**, with `complete:true`, no infrastructure errors, and process exit status **1**. The failure is `AI::OpenAI jsonSchemaPrompt unsupported provider`: the test expects `JSON Schema responses not supported by this provider`, while the implementation throws `Error: LLM_DECISION_INVALID_REQUEST`. The same failure was reproduced using the original `js/owrap.test.js` from HEAD with the same AI implementation. It is outside this modernization and was not changed. This full run preceded the final focused cleanup/encoding/worker-argument fixes; those are covered by the final focused validation.
+
+Final validation against the serially rebuilt artifact:
+
+- **73 independent framework checks passed** (`tests/runTestFramework.js`).
+- **25 extension/integration checks passed** (`tests/runTestExtensions.js`): generators/shrinking, contracts/replay, message ordering, model exploration, coverage/benchmarks/mutation results, manifest rejection, oJob-common success/failure propagation, live loopback HTTP, prepared H2 queries, private channels, and Z3 sat/unsat/parser-error outcomes.
+- All five package smoke entry points passed; their manifests/file hashes were regenerated.
+- Lazy core modules and a workflow worker also passed from an unrelated working directory.
+- JAR ZIP integrity and packaged JS matching generated build sources passed. CI YAML parsing, shell syntax and whitespace checks passed.
+
+Reproduction from the core checkout:
+
+```sh
+java -Dopenaf.test.worker=true -jar openaf.jar -c "try { loadLib('tests/runTestFramework.js'); exit(2); } catch(e) { printErr(e); exit(1); }"
+OW_TEST_COMMON=../oJob-common OW_TEST_LIVE=1 OW_TEST_Z3=/path/to/z3 \
+ java -Dopenaf.test.worker=true -jar openaf.jar -c "try { loadLib('tests/runTestExtensions.js'); exit(2); } catch(e) { printErr(e); exit(1); }"
+```
+
+The extension runner defaults to the sibling `openaf-opacks`; override `OW_TEST_OPACK_ROOT` when needed. Omit `OW_TEST_LIVE`, `OW_TEST_Z3`, or `OW_TEST_COMMON` to skip their optional checks. The core runner uses `OW_TEST_SOURCE=1` for source-loading development checks.
+
+Local validation uses macOS and Java 27. The new CI matrix targets Linux/macOS/Windows on Java 21 and 25, but hosted results are pending. Socket-dependent validation requires permission to bind local ports. Z3 5.3.3 was already installed and was used for sat/unsat/parser-error checks; no solver installation was performed.
+
+Builds use the repository's `build.yaml`. A final packaging attempt overlapped an oPack command opening the JAR and hit a ZIP-header race; that run was stopped, and final validation uses a serial rebuild from a separate, validated copy of the current `openaf.jar`/`openaf.jar.orig` pair. Do not launch consumers of the output JAR until repacking and completion generation have finished.
+
+## Deliberately gated or incomplete work
+
+| Capability | Current boundary | Next evidence needed |
+|---|---|---|
+| Native JS Promise | Rejected; oPromise and Future supported | Engine-owned queue/rejection/context tests in interpreted and compiled modes |
+| `from`/`to` component traces | Only actual scheduled jobs are reported; composition semantics remain intact | A source-map/instrumentation PoC preserving lexical scope, returns, exceptions and language adapters |
+| Automatic JS coverage | Explicit probes only | A parser/debugger implementation with source identity, compiled/interpreted parity and semantic-preservation regressions |
+| Java coverage | No JaCoCo orchestration | Optional version-pinned JVM agent integration and JDK compatibility tests |
+| Automatic mutation generation / weak-assertion analysis | Explicit mutation spans and caller-provided runner only | Safe AST operators, isolated runner, equivalent-mutant handling and cost budgets |
+| Untrusted execution | Denied without an administrator-provided sandbox adapter and explicit policy | Real OS/container providers with negative escape/resource-limit tests on supported platforms |
+| AI source-to-test generation | Manifests and execution interface supplied; no generation agent bundled | External mini-a/agent integration, controlled generation/evaluation corpus and sandbox provider |
+| MCP execution/replay publication | Read-only descriptors supplied; servers start only by explicit host integration | Authenticated host tool adapter backed by a concrete sandbox policy |
+| Lean proof checking | Explicit backend interface only | Maintained formal specification, theorem identity, reproducible checker artifact and model-to-code assumptions |
+| Universal JSON Schema generators | A bounded, documented subset; unsupported keywords reject | Solver-backed generation or bounded rejection with explicit unsatisfiable-schema outcomes |
+| Cross-platform runtime proof | CI matrix configured | Passing hosted jobs on all six OS/JDK combinations |
+
+Generic Java Future cancellation does not prove termination. On timeout its session is poisoned and resources are retained rather than cleaned up while unknown work may still be active. For owned tasks, cleanup waits for confirmed termination. JVM subprocess isolation does not restrict filesystem/network permissions, and descendant enumeration can be denied by the OS. Hard untrusted-code limits require the separate sandbox provider.
+
+## Review and release units
+
+1. Kernel, reporting, legacy regressions and CI outcome checks.
+2. Assertions/schema factory, suites/fixtures and concurrent scheduling.
+3. Mocks and async ownership/cancellation.
+4. Bounded process support, workflow observer/transform seams and worker tests.
+5. oJob-common wrapper fixes and adapters (separate repository).
+6. Five optional oPacks, each independently reviewable and installable (separate repository).
+7. Published API guide, schema and feasibility-gated follow-ups.
+
+These changes are uncommitted. No PR, push, release or package publication was performed. Existing unrelated workspace changes remain outside the implementation scope.
diff --git a/docs/plans/ow-test-modernization.md b/docs/plans/ow-test-modernization.md
new file mode 100644
index 000000000..976439b03
--- /dev/null
+++ b/docs/plans/ow-test-modernization.md
@@ -0,0 +1,1504 @@
+# OpenAF `ow.test` modernization plan
+
+**Intended document:** `docs/plans/ow-test-modernization.md`
+**Status:** Accepted architecture and implementation specification. Implementation authorized on 2026-11-06; see [implementation status](./ow-test-implementation-status.md) for delivered capabilities and validation.
+**Repository baseline:** `8a56ade2e5438c9ebec68f83088460faea406b68`, inspected on 2026-11-06.
+
+## 1. Executive summary
+
+Modernize `ow.test` around a small, reliable execution kernel, while retaining its immediate-execution API and dependency-light character.
+
+The foundation should provide:
+
+- Explicit execution sessions.
+- Exactly-once execution finalization.
+- Thread-safe counters, profiling, and result collection.
+- Structured, serializable results.
+- Precise assertions.
+- Lifecycle and resource ownership.
+- Optional extensions that consume the same execution and result contracts.
+
+OpenAF already supplies most underlying primitives: Java locks and atomics, channels, oPromises, process execution, HTTP clients and servers, JDBC, JSON Schema validation, instrumentation, and oJob execution. The modernization should compose these facilities rather than import another testing framework.
+
+The user selected **fresh OpenAF processes as the default isolation boundary for native oJob tests**. This provides state separation and enforceable process deadlines. It does not, by itself, sandbox filesystem, network, or credential access.
+
+### Top 10 recommendations
+
+| Rank | Improvement | Impact | Relative effort |
+|---|---|---|---|
+| 1 | Repair profiling, destructive history reads, and duplicate finalization | Essential correctness | Low–medium |
+| 2 | Introduce immutable execution records and isolated sessions | Foundation for every later feature | High |
+| 3 | Preserve default failure recording while adding explicit throwing and fail-fast policies | Reliable composition without breaking suites | Medium |
+| 4 | Add structured assertion errors and precise equality APIs | Better diagnostics for people and agents | Medium–high |
+| 5 | Correct JUnit/Markdown output and fail-closed CI result handling | Prevent misleading CI results | Low–medium |
+| 6 | Add suites, hooks, fixtures, and guaranteed cleanup | Reduces repetitive test infrastructure | High |
+| 7 | Build native oJob testing with isolated workers and explicit execution events | Highest strategic OpenAF-specific value | Very high |
+| 8 | Add scoped mocks and spies with ownership and restoration | Deterministic dependency isolation | Medium |
+| 9 | Add eventual assertions and explicit oPromise/Future adapters | Practical asynchronous testing | Medium |
+| 10 | Build optional property, contract, coverage, and verification modules on the same result model | Extensibility without core overhead | High, incremental |
+
+### Top 5 quick wins
+
+1. Replace the arrow-function min/max getters and remove singleton references from profile enumeration.
+2. Make `getExecHistory()` return detached data.
+3. Prevent duplicate timer completion, especially after nonzero external exit.
+4. Correct JUnit root counts and empty-result handling.
+5. Correct nonexistent `profile()` documentation and make missing/stale CI result files fail explicitly.
+
+### Recommended order
+
+**Phase 1 → Phase 2 → basic Phase 6 → Phase 3 → Phase 4 → Phases 5/7 → advanced Phase 6 → Phase 8 → Phase 9.**
+
+Machine-readable results and reproducibility belong in P0; LLM integration remains P3.
+
+### Major architecture decisions
+
+- Keep existing public entry points and default failure behavior.
+- Use an in-memory, session-owned result store as the authority; channels are compatibility views or export destinations.
+- Separate correctness events from sampled instrumentation.
+- Load extensions lazily.
+- Run existing oJobs in fresh processes by default.
+- Keep protocol-specific adapters and advanced verification in optional oPacks.
+- Treat generated tests as executable, untrusted programs.
+- Never describe successful tests as mathematical proofs.
+
+### Recommended first implementation PR
+
+**“Fix ow.test profile getters, history snapshots, and JUnit counts.”**
+
+Limit it to the existing API, focused regressions, and documentation corrections. Cover min/max binding, receiver-local profile enumeration, repeated history reads, correct JUnit root counts, and empty XML output. Introduce no suite API or dependencies. Follow with a separate execution-finalization/concurrency PR.
+
+---
+
+## 2. Current implementation inventory
+
+### Evidence classification
+
+- **Verified source:** directly observed in the checkout.
+- **Verified probe:** reproduced using the existing local JAR, version `20261106`, with checkout `js/owrap.test.js` explicitly loaded.
+- **Proposal:** new behavior described in this document.
+- **PoC gate:** feasibility must be demonstrated before exposing the capability.
+
+The probes ran on macOS with Java 27. They are not Linux/Windows validation or proof that a newly built package behaves identically. No full suite or rebuild was performed. Probe-generated compilation caches were removed, and the original working-tree changes were preserved.
+
+The local `oJob-common/oJobTest.yaml` was inspected, but it is not tracked by this repository. Findings about it describe that installed snapshot; companion changes require verification in its owning repository.
+
+| Area | Existing implementation and exact integration points | Assessment |
+|---|---|---|
+| Test initialization | [js/openaf.js:7507](../../js/openaf.js#L7507), `OpenWrap.prototype.loadTest()`; [js/owrap.test.js:5](../../js/owrap.test.js#L5), `OpenWrap.test()` | Loads compiled code and initializes a singleton. No session factory. |
+| Counters and reset | `owrap.test.js`, `getCountTest/Pass/Fail/Assert()`, `reset()` | Atomic individual counters; reset destroys/recreates the fixed result channel and resets configuration. |
+| Assertions | `owrap.test.js:183`, `assert()`; `openaf.js:5065`, `compare()` | One equality assertion, throwing a string. Equality inherits `compare()` limitations. |
+| Profiling | `owrap.test.js:46–124`, getters; `start()` at 197; `stop()` at 222 | Shared key timestamps; partial atomicity; wall-clock duration calculation. |
+| Execution | `owrap.test.js:249`, `testExternally()`; 327, `test()` | Immediate execution, return body output on success, catch and record failures. |
+| Results | `getChannel()` at 409; `getExecHistory()` at 418 | Fixed `__owTest::tests` channel; records grouped by message, containing atomic objects and mutable execution arrays. |
+| Reporting | `toMarkdown()` at 433; `toJUnitXML()` at 482 | Built-in Markdown and XML; no versioned core JSON result envelope. |
+| Legacy test script | [tests/autoTestAll.js](../../tests/autoTestAll.js) | Separate older test harness with plug callbacks and wrapper counters. It is not the area-YAML discovery mechanism. |
+| Current orchestration | [tests/autoTestAll.yaml](../../tests/autoTestAll.yaml), `autoTestAll.allJobs.yaml`, area YAML/JS pairs | Explicit YAML registration of exported functions. Main orchestrator enables asynchronous execution and exposes channels. |
+| Existing oJob testing | Local `oJob-common/oJobTest.yaml`: `oJob Test`, `oJob Assert`, report jobs, `oJob Test CI summary` | Supports functions, named jobs, repetition, `$path` output assertions, and reporting. It is more capable than a simple assertion wrapper, but lacks isolated workflow traces. |
+| Concurrency | `openaf.js`: `$atomic()` at 15898, `syncFn()` at 7189, `$do()` at 16375, `$doWait()` at 16425, `pForEach()` at 6618, `$tb()` at 8721; `src/openaf/plugins/Threads.java` | Native reusable primitives. `$doWait()` does not automatically throw a rejected task’s exception or cancel a pending task after its wait deadline. |
+| Runtime | [src/openaf/rhino/RhinoEngine.java:85](../../src/openaf/rhino/RhinoEngine.java#L85); `pom.xml` | Rhino ES6 mode; declared Rhino dependencies are 1.9.2. Ordinary Node/browser event-loop assumptions are invalid. |
+| Timing and metrics | `openaf.js`, `now()`, `nowNano()`; `owrap.metrics.js`; `owrap.format.js:3927`, `percentile()` | Wall and monotonic clocks already exist. Percentile calculation sorts its input array in place. |
+| JVM profiling | `owrap.java.js`, `jcmd()`, `pidStartJFR()`, `pidStopJFR()`, `pidDumpJFR()`, `parseJFR()`, `pidThreadDump()` | Reuse for optional benchmark diagnostics; not correctness coverage. |
+| Instrumentation | [js/owrap.instrumentation.js](../../js/owrap.instrumentation.js), `startSpan()`, `withSpan()`, `bind()`, `withContext()`, provider registration | Thread-local context, monotonic timing, idempotent span completion, protected exporters. Disabled by default. |
+| Instrumented integration boundaries | `owrap.oJob.js:2808`; `openaf.js` oPromise/thread-box bindings; HTTP wrappers | Useful trace correlation. Sampling, filters, swallowed provider errors, and handled exceptions prevent using telemetry alone as authoritative test evidence. |
+| Development wrapping | `owrap.dev.js:295–489`, `JSDebug`, `setFn()`, `unSetFn()`, `setTestingWrap()` | Existing source rewriting and global tracking, with isolation/restoration limitations. |
+| Debug preparsing | `owrap.debug.js`, `register()`, `debug()`, `load()`, `require()` | Comment-based checkpoints, profiling and assertions. Not a coverage engine. |
+| AST support | `src/openaf/AFBase.java:1379`, `parse()`; `src/openaf/CompileJS2Java.java` | Rhino parser is available. `af.parse()` returns top-level statement source, not a complete coverage-ready AST interface. |
+| Channels | `owrap.ch.js`, `simple` backend at 1293, `create/get/set/getAll/subscribe()` | Operations use locks, but values can be returned by reference; multi-operation read/modify/write sequences are not transactions. |
+| HTTP/REST | `openaf.js`, `$rest()`; `owrap.obj.js`, `http`, `rest.connectionFactory()`, explicit `httpClient`; `owrap.server.js`, `httpd.start/route/stop()` | Reuse explicit clients and loopback fixtures. Connection/read/write/call timeouts exist. |
+| JDBC | `src/openaf/DB.java`, `src/openaf/core/DB.java`, `qs/us/commit/rollback`; `tests/autoTestAll.DB.js` | Real DB wrapper and existing fake JDBC-interface tests. Some batch APIs commit internally. |
+| MCP | `openaf.js:10160`, `$mcp()`, `initialize/listTools/callTool/destroy`; `owrap.server.js`, `mcpStdio()`, `replyJSONRPC()` | Existing clients, servers, schema metadata, and local protocol fixtures. No LLM required. |
+| JSON Schema | `owrap.obj.js`, `schemaInit/Compile/Validate/Add/Remove/Generator`; [docs/json-schema.md](../../docs/json-schema.md) | Bundled Ajv with draft-07, 2019-09, 2020-12 routing. Initialization is global and first-call-wins; defaults can mutate validated input. |
+| Processes | `src/openaf/AFBase.java`, `sh()`; `openaf.js`, `$sh()`; [src/openaf/OJobLanguageProcess.java](../../src/openaf/OJobLanguageProcess.java) | Structured exit results and a process-tree deadline implementation exist. Current language runner inherits environment and captures unbounded output. |
+| Temporary resources | `src/openaf/core/IO.java`, `createTempFile()` and `createTempDir()` | Reuse these rather than inventing naming or directory utilities. |
+| Ports | `HTTPServer.java`, `newHTTPd()` and `getPort()` | Nonpositive ports currently invoke find-free-port then bind; this has a reservation race. |
+| Build and packaging | `buildos.js`, `build.yaml`, `jsmin/`, `jslib/`, compiled libraries | New wrapper modules must work through compilation and installed-JAR loading, not only source loading. |
+| CI | `oafTest.sh`; `.github/workflows/build-and-test.yml`; `publish-maven.yml` | Multiple result checks exist with different strictness. Cross-platform language tests already provide a matrix pattern. |
+| Documentation | `docs/testing.md`, `docs/authoring-testing.md`, `docs/openaf.md`, `docs/instrumentation.md` | Useful guidance, but contributor testing docs contain API and lifecycle inaccuracies. |
+
+No reusable `ow.test` property-testing, mutation-testing, formal-verification, or statement/branch-coverage implementation was found in the inspected framework paths.
+
+---
+
+## 3. Verified bugs and architectural limitations
+
+### Defects and required regressions
+
+| ID | Finding and evidence | Required regression |
+|---|---|---|
+| B01 | `getProfileMax()` and `getProfileMin()` use lexical `this` through prototype arrow functions. Probe throws reading `__profile`. | Invoke both through `ow.test` and a session receiver after known samples. |
+| B02 | `start()` replaces one timestamp per key. Nested or concurrent uses overwrite each other. Probe outer timing excluded time before the inner start. | Nested same-key timers and coordinated same-key workers preserve independent intervals. |
+| B03 | `testExternally()` stops before checking exit status, then stops again in `catch`. One `/usr/bin/false` invocation produced two profile hits. | One failed command produces one execution, one failure, one timing sample. |
+| B04 | Profile initialization, `sum.getSet(sum.get()+elapsed)`, min/max updates, history lookup, and array updates are not collectively atomic. A probe requesting 400 same-name tests retained 396 execution entries and 398 record hits. | Barrier-coordinated workers retain every execution and reconcile all counters. |
+| B05 | `getExecHistory()` mutates live channel values by replacing atomic fields with numbers. A second call fails. | Repeated reads, reporting after reads, and further same-name tests remain valid. |
+| B06 | Missing profiles throw incidental property errors; reset profiles yield `NaN` averages; `getProfile().start` changes type before/after first start. | Explicit empty-state values; no atomic objects in snapshot output. |
+| B07 | `getAllProfile*()` delegates to global `ow.test` rather than its receiver. | Two independent receivers cannot read each other’s profile values. |
+| B08 | Logging/channel writes occur within execution success/failure paths; failures there can trigger a second stop or conflicting counters. `setResult()` logs even with output disabled. | Throwing logger/exporter tests finalize once; disabled output suppresses callback logging. |
+| B09 | JUnit root `tests` increments per suite, not testcase. Probe emitted root `tests="1"` for four cases. | Root test count equals the sum of emitted testcase counts. |
+| B10 | Empty JUnit reporting dereferences a missing minimum. Probe throws. | Empty results produce valid zero-count XML. |
+| B11 | Ordinary XML metacharacters are escaped correctly by `XMLBuilder2`; illegal XML characters are not normalized. NUL in a failure caused serialization failure. | Round-trip `<>&"'`; sanitize illegal XML 1.0 characters without double escaping. |
+| B12 | Markdown includes unescaped names/results and raw HTML. Probe broke rows with pipes/newlines and retained `