Merge pull request 'Preserve both pre-cutoff dependency branch histories' (#11) from migration/cutoff-2cec82bf4aa9-68d7f8 into dependabot/github_actions/actions/setup-java-6.1.0

Bumps [actions/setup-java](https://github.com/actions/setup-java) from 5.2.0 to 6.1.0.
- [Release notes](https://github.com/actions/setup-java/releases)
- [Commits](https://github.com/actions/setup-java/compare/be666c2fcd27ec809703dec50e508c2fdc7f6654...b843ebf9b913146b38da2eaa7aeddf76074ae1ad)

---
updated-dependencies:
- dependency-name: actions/setup-java
  dependency-version: 6.1.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 name: Bug report
 description: Report a reproducible printing QBit issue.
 title: 'bug: '

.github/ISSUE_TEMPLATE/config.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 blank_issues_enabled: true
 contact_links:
   - name: Report a security vulnerability privately

.github/dependabot.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 version: 2
 updates:
   - package-ecosystem: maven

.github/pyrightconfig.json

@@ -0,0 +1,15 @@
+{
+  "typeCheckingMode": "strict",
+  "pythonVersion": "3.13",
+  "include": [
+    "scripts/*.py"
+  ],
+  "reportMissingTypeStubs": "error",
+  "reportUnnecessaryTypeIgnoreComment": "error",
+  "reportImplicitOverride": "error",
+  "exclude": [
+    "**/__pycache__"
+  ],
+  "venvPath": "..",
+  "venv": ".venv"
+}

.github/scripts/check-codeql-sarif.py

@@ -1,53 +1,108 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 """Reject missing/malformed CodeQL evidence before enforcing the severity gate."""
+
 import json
 import math
 import os
 from pathlib import Path
+from typing import TypedDict
+
+RuleProperties = TypedDict("RuleProperties", {"security-severity": str | float | None}, total=False)
 
 
-def check(directory, language, threshold):
-    if not math.isfinite(threshold) or not 0 <= threshold <= 10:
-        raise ValueError("Invalid security severity threshold")
-    canonical = {"java-kotlin": "java", "javascript-typescript": "javascript", "c-cpp": "cpp"}.get(language, language)
-    files = sorted(Path(directory).glob("*.sarif"))
-    if not canonical or not any(path.name == canonical + ".sarif" for path in files):
-        raise ValueError("Missing expected CodeQL SARIF report for " + language)
-    blocking = []
-    for path in files:
-        report = json.loads(path.read_text(encoding="utf-8"))
-        runs = report.get("runs")
-        if report.get("version") != "2.1.0" or not isinstance(runs, list) or not runs:
-            raise ValueError("Invalid or empty SARIF runs: " + path.name)
-        for run in runs:
-            driver = run.get("tool", {}).get("driver", {})
-            results = run.get("results")
-            if driver.get("name") != "CodeQL" or not isinstance(driver.get("rules"), list) or not isinstance(results, list):
-                raise ValueError("Missing CodeQL tool/rules/results evidence: " + path.name)
-            rules = {}
-            for component in [driver, *run.get("tool", {}).get("extensions", [])]:
-                for rule in component.get("rules", []):
-                    rules[rule["id"]] = rule
-            if not rules:
-                raise ValueError("CodeQL report has no analyzed rule metadata: " + path.name)
-            for invocation in run.get("invocations", []):
-                if invocation.get("executionSuccessful") is False:
-                    raise ValueError("CodeQL invocation failed: " + path.name)
-            for result in results:
-                rule_id = result.get("ruleId") or result.get("rule", {}).get("id")
-                if rule_id not in rules:
-                    raise ValueError("Result references missing rule metadata: " + path.name)
-                if result.get("suppressions"):
-                    continue
-                severity = float(rules[rule_id].get("properties", {}).get("security-severity", 0) or 0)
-                if not math.isfinite(severity) or not 0 <= severity <= 10:
-                    raise ValueError("Invalid rule severity: " + rule_id)
-                if severity >= threshold:
-                    blocking.append((severity, rule_id))
-    for severity, rule_id in sorted(blocking, reverse=True):
-        print(f"::error title=CodeQL security finding::{rule_id} ({severity})")
-    print(f"Validated {len(files)} SARIF report(s); {len(blocking)} blocking result(s)")
-    return bool(blocking)
+class Rule(TypedDict):
+   """Keep the rule identity and optional severity metadata used by the gate."""
+
+   id: str
+   properties: RuleProperties
+
+
+class Component(TypedDict, total=False):
+   """Describe CodeQL driver or extension rule metadata."""
+
+   name: str
+   rules: list[Rule]
+
+
+class Tool(TypedDict, total=False):
+   """Group the driver and optional extension rule catalogs."""
+
+   driver: Component
+   extensions: list[Component]
+
+
+class Result(TypedDict, total=False):
+   """Describe only the result fields consumed by the severity gate."""
+
+   ruleId: str
+   rule: dict[str, str]
+   suppressions: list[object]
+
+
+class Run(TypedDict, total=False):
+   """Retain invocation success and findings for one analyzed language."""
+
+   tool: Tool
+   results: list[Result]
+   invocations: list[dict[str, bool]]
+
+
+class Report(TypedDict, total=False):
+   """Represent SARIF fields while retaining the explicit runtime validation."""
+
+   version: str
+   runs: list[Run]
+
+
+MAX_SEVERITY = 10
+
+
+def check(directory: str | Path, language: str, threshold: float) -> bool:  # noqa: PLR0912 -- Keep the ordered evidence checks together; none may be skipped.
+   """Validate complete CodeQL evidence and report findings at the threshold."""
+   if not math.isfinite(threshold) or not 0 <= threshold <= MAX_SEVERITY:
+      raise ValueError("Invalid security severity threshold")
+   canonical = {"java-kotlin": "java", "javascript-typescript": "javascript", "c-cpp": "cpp"}.get(language, language)
+   files = sorted(Path(directory).glob("*.sarif"))
+   if not canonical or not any(path.name == canonical + ".sarif" for path in files):
+      raise ValueError("Missing expected CodeQL SARIF report for " + language)
+   blocking: list[tuple[float, str]] = []
+   for path in files:
+      report: Report = json.loads(path.read_text(encoding="utf-8"))
+      runs = report.get("runs")
+      if report.get("version") != "2.1.0" or not isinstance(runs, list) or not runs:
+         raise ValueError("Invalid or empty SARIF runs: " + path.name)
+      for run in runs:
+         driver = run.get("tool", {}).get("driver", {})
+         results = run.get("results")
+         if driver.get("name") != "CodeQL" or not isinstance(driver.get("rules"), list) or not isinstance(results, list):
+            raise ValueError("Missing CodeQL tool/rules/results evidence: " + path.name)
+         rules: dict[str, Rule] = {}
+         for component in [driver, *run.get("tool", {}).get("extensions", [])]:
+            for rule in component.get("rules", []):
+               rules[rule["id"]] = rule
+         if not rules:
+            raise ValueError("CodeQL report has no analyzed rule metadata: " + path.name)
+         for invocation in run.get("invocations", []):
+            if invocation.get("executionSuccessful") is False:
+               raise ValueError("CodeQL invocation failed: " + path.name)
+         for result in results:
+            rule_id = result.get("ruleId") or result.get("rule", {}).get("id")
+            if rule_id not in rules:
+               raise ValueError("Result references missing rule metadata: " + path.name)
+            if result.get("suppressions"):
+               continue
+            severity = float(rules[rule_id].get("properties", {}).get("security-severity", 0) or 0)
+            if not math.isfinite(severity) or not 0 <= severity <= MAX_SEVERITY:
+               raise ValueError("Invalid rule severity: " + rule_id)
+            if severity >= threshold:
+               blocking.append((severity, rule_id))
+   for severity, rule_id in sorted(blocking, reverse=True):
+      print(f"::error title=CodeQL security finding::{rule_id} ({severity})")
+   print(f"Validated {len(files)} SARIF report(s); {len(blocking)} blocking result(s)")
+   return bool(blocking)
 
 
 if __name__ == "__main__":
-    raise SystemExit(1 if check(os.environ["SARIF_DIR"], os.environ["EXPECTED_LANGUAGE"], float(os.environ["THRESHOLD"])) else 0)
+   raise SystemExit(1 if check(os.environ["SARIF_DIR"], os.environ["EXPECTED_LANGUAGE"], float(os.environ["THRESHOLD"])) else 0)

.github/scripts/check-maven-inventory.py

@@ -1,125 +1,173 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 """Fail closed unless scanners cover Maven's selected UI-host runtime graph."""
+
 import argparse
-from collections import Counter
 import json
-from pathlib import Path
 import re
+from collections import Counter
+from pathlib import Path
+from typing import TypedDict, cast
 from urllib.parse import unquote, urlsplit
 
 
+class Bom(TypedDict, total=False):
+   """Describe the selected CycloneDX coordinate fields."""
+
+   bomFormat: str
+   components: list[dict[str, str]]
+   metadata: dict[str, dict[str, str]]
+
+
+class TrivyReport(TypedDict, total=False):
+   """Describe package coordinates, leaving runtime shape checks intact."""
+
+   Results: list[dict[str, list[dict[str, str]]]]
+
+
+class OsvReport(TypedDict, total=False):
+   """Keep result bodies untrusted until their explicit validation."""
+
+   results: list[object]
+
+
+class OsvResult(TypedDict, total=False):
+   """Describe source identity and packages after checking the object shape."""
+
+   source: dict[str, str]
+   packages: list[object]
+
+
+class OsvEntry(TypedDict, total=False):
+   """Describe the coordinate and optional vulnerability array being checked."""
+
+   package: dict[str, str]
+   vulnerabilities: object
+
+
 REQUIRED = {
-    "com.kingsrook.qqq:qqq-frontend-next",
-    "com.kingsrook.qqq:qqq-backend-core",
-    "com.kingsrook.qqq:qqq-backend-module-filesystem",
-    "com.google.guava:guava",
-    "com.h2database:h2",
+   "com.kingsrook.qqq:qqq-frontend-next",
+   "com.kingsrook.qqq:qqq-backend-core",
+   "com.kingsrook.qqq:qqq-backend-module-filesystem",
+   "com.google.guava:guava",
+   "com.h2database:h2",
 }
 REVIEWED_H2_VERSION = "2.4.240"
 OMITTED = object()
 
 
-def resolved(text):
-    packages = set()
-    for line in text.splitlines():
-        line = re.sub(r"\x1b\[[0-9;]*m", "", line).strip().split(" -- ", 1)[0].strip()
-        if not line or line == "The following files have been resolved:":
-            continue
-        parts = line.split(":")
-        if len(parts) not in (5, 6) or parts[-1] not in ("compile", "runtime"):
-            raise ValueError(f"Unexpected Maven runtime coordinate: {line}")
-        if not all(parts) or parts[2] != "jar":
-            raise ValueError(f"Invalid runtime JAR coordinate: {line}")
-        name = parts[0] + ":" + parts[1]
-        if parts[0].startswith(("org.junit", "org.opentest4j", "org.apiguardian")):
-            raise ValueError("Test library in runtime inventory")
-        packages.add((name, parts[-2]))
-    if not REQUIRED.issubset({name for name, _ in packages}):
-        raise ValueError("Maven inventory is empty or lacks required UI-host dependencies")
-    # The pinned dependency-review license exception matcher ignores versions.
-    # Keep any H2 metadata exception limited to the reviewed, unmodified runtime.
-    if {version for name, version in packages if name == "com.h2database:h2"} != {REVIEWED_H2_VERSION}:
-        raise ValueError("H2 runtime must match reviewed version " + REVIEWED_H2_VERSION)
-    return packages
+def resolved(text: str) -> set[tuple[str, str]]:
+   """Read Maven's selected runtime JARs and enforce the reviewed H2 pin."""
+   packages: set[tuple[str, str]] = set()
+   for raw_line in text.splitlines():
+      line = re.sub(r"\x1b\[[0-9;]*m", "", raw_line).strip().split(" -- ", 1)[0].strip()
+      if not line or line == "The following files have been resolved:":
+         continue
+      parts = line.split(":")
+      if len(parts) not in (5, 6) or parts[-1] not in ("compile", "runtime"):
+         raise ValueError(f"Unexpected Maven runtime coordinate: {line}")
+      if not all(parts) or parts[2] != "jar":
+         raise ValueError(f"Invalid runtime JAR coordinate: {line}")
+      name = parts[0] + ":" + parts[1]
+      if parts[0].startswith(("org.junit", "org.opentest4j", "org.apiguardian")):
+         raise ValueError("Test library in runtime inventory")
+      packages.add((name, parts[-2]))
+   if not REQUIRED.issubset({name for name, _ in packages}):
+      raise ValueError("Maven inventory is empty or lacks required UI-host dependencies")
+   # The pinned dependency-review license exception matcher ignores versions.
+   # Keep any H2 metadata exception limited to the reviewed, unmodified runtime.
+   if {version for name, version in packages if name == "com.h2database:h2"} != {REVIEWED_H2_VERSION}:
+      raise ValueError("H2 runtime must match reviewed version " + REVIEWED_H2_VERSION)
+   return packages
 
 
-def components(report):
-    if not isinstance(report, dict) or report.get("bomFormat") != "CycloneDX":
-        raise ValueError("Expected CycloneDX inventory")
-    packages = set()
-    for component in report.get("components", []):
-        purl = urlsplit(component.get("purl", ""))
-        if purl.scheme != "pkg" or not purl.path.startswith("maven/"):
-            raise ValueError("Missing Maven package URL")
-        coordinate, version = purl.path.removeprefix("maven/").rsplit("@", 1)
-        group, artifact = coordinate.split("/", 1)
-        packages.add((unquote(group) + ":" + unquote(artifact), unquote(version)))
-    if not packages:
-        raise ValueError("Empty CycloneDX inventory")
-    return packages
+def components(report: object) -> set[tuple[str, str]]:
+   """Extract exact Maven coordinates from the scanner's CycloneDX inventory."""
+   typed_report = cast(Bom, report)
+   if not isinstance(report, dict) or typed_report.get("bomFormat") != "CycloneDX":
+      raise ValueError("Expected CycloneDX inventory")
+   packages: set[tuple[str, str]] = set()
+   for component in typed_report.get("components", []):
+      purl = urlsplit(component.get("purl", ""))
+      if purl.scheme != "pkg" or not purl.path.startswith("maven/"):
+         raise ValueError("Missing Maven package URL")
+      coordinate, version = purl.path.removeprefix("maven/").rsplit("@", 1)
+      group, artifact = coordinate.split("/", 1)
+      packages.add((unquote(group) + ":" + unquote(artifact), unquote(version)))
+   if not packages:
+      raise ValueError("Empty CycloneDX inventory")
+   return packages
 
 
-def check(expected, bom, trivy=OMITTED):
-    actual = components(bom)
-    if actual != expected:
-        raise ValueError(f"Maven/SBOM mismatch: missing={sorted(expected - actual)}, extra={sorted(actual - expected)}")
-    if trivy is not OMITTED:
-        if not isinstance(trivy, dict) or not isinstance(trivy.get("Results"), list):
-            raise ValueError("Expected Trivy report object with Results array")
-        scanned = {(p["Name"], p["Version"]) for r in trivy.get("Results", []) for p in r.get("Packages", [])}
-        # Trivy also reports the root project represented by SBOM metadata.
-        root = bom.get("metadata", {}).get("component", {})
-        allowed = expected | {(root.get("group", "") + ":" + root.get("name", ""), root.get("version", ""))}
-        if not expected.issubset(scanned) or not scanned.issubset(allowed):
-            raise ValueError(f"Maven/Trivy mismatch: missing={sorted(expected - scanned)}, extra={sorted(scanned - allowed)}")
-    return len(expected)
+def check(expected: set[tuple[str, str]], bom: object, trivy: object = OMITTED) -> int:
+   """Require exact SBOM coverage and, when supplied, selected Trivy coverage."""
+   actual = components(bom)
+   if actual != expected:
+      raise ValueError(f"Maven/SBOM mismatch: missing={sorted(expected - actual)}, extra={sorted(actual - expected)}")
+   if trivy is not OMITTED:
+      typed_trivy = cast(TrivyReport, trivy)
+      if not isinstance(trivy, dict) or not isinstance(typed_trivy.get("Results"), list):
+         raise ValueError("Expected Trivy report object with Results array")
+      scanned = {(p["Name"], p["Version"]) for r in typed_trivy.get("Results", []) for p in r.get("Packages", [])}
+      # Trivy also reports the root project represented by SBOM metadata.
+      root = cast(Bom, bom).get("metadata", {}).get("component", {})
+      allowed = expected | {(root.get("group", "") + ":" + root.get("name", ""), root.get("version", ""))}
+      if not expected.issubset(scanned) or not scanned.issubset(allowed):
+         raise ValueError(f"Maven/Trivy mismatch: missing={sorted(expected - scanned)}, extra={sorted(scanned - allowed)}")
+   return len(expected)
 
 
-def check_osv(expected, report):
-    if not isinstance(report, dict) or not isinstance(report.get("results"), list):
-        raise ValueError("Expected OSV report object with results array")
-    # OSV 2.6.0 queries CycloneDX purls but omits Maven groups in JSON names:
-    # https://github.com/google/osv-scanner/issues/3099
-    # Fail on ambiguous display coordinates instead of claiming full identity proof.
-    projected = Counter((name.split(":", 1)[1], version) for name, version in expected)
-    if any(count != 1 for count in projected.values()):
-        raise ValueError("Ambiguous Maven coordinates in pinned OSV report format")
-    scanned = Counter()
-    for result in report["results"]:
-        if not isinstance(result, dict) or not isinstance(result.get("source"), dict):
-            raise ValueError("Missing OSV source")
-        if result["source"].get("type") != "sbom" or not isinstance(result["source"].get("path"), str):
-            raise ValueError("Expected OSV SBOM source")
-        if not isinstance(result.get("packages"), list):
-            raise ValueError("Missing OSV package inventory; use --all-packages")
-        for entry in result["packages"]:
-            if not isinstance(entry, dict) or not isinstance(entry.get("package"), dict):
-                raise ValueError("Malformed OSV package")
-            package = entry["package"]
-            if package.get("ecosystem") != "Maven" or not all(isinstance(package.get(k), str) and package[k] for k in ("name", "version")):
-                raise ValueError("Invalid OSV Maven package coordinate")
-            if "vulnerabilities" in entry and not isinstance(entry["vulnerabilities"], list):
-                raise ValueError("Malformed OSV vulnerabilities")
-            scanned[(package["name"], package["version"])] += 1
-    if scanned != projected:
-        raise ValueError("OSV --all-packages inventory differs from selected Maven graph")
-    return len(expected)
+def check_osv(expected: set[tuple[str, str]], report: object) -> int:
+   """Reject missing, ambiguous, malformed or partial OSV package evidence."""
+   typed_report = cast(OsvReport, report)
+   if not isinstance(report, dict) or not isinstance(typed_report.get("results"), list):
+      raise ValueError("Expected OSV report object with results array")
+   # OSV 2.6.0 queries CycloneDX purls but omits Maven groups in JSON names:
+   # https://github.com/google/osv-scanner/issues/3099
+   # Fail on ambiguous display coordinates instead of claiming full identity proof.
+   projected = Counter((name.split(":", 1)[1], version) for name, version in expected)
+   if any(count != 1 for count in projected.values()):
+      raise ValueError("Ambiguous Maven coordinates in pinned OSV report format")
+   scanned: Counter[tuple[str, str]] = Counter()
+   for raw_result in cast(list[object], typed_report.get("results")):
+      result = cast(OsvResult, raw_result)
+      if not isinstance(raw_result, dict) or not isinstance(result.get("source"), dict):
+         raise ValueError("Missing OSV source")
+      source = cast(dict[str, str], result.get("source"))
+      if source.get("type") != "sbom" or not isinstance(source.get("path"), str):
+         raise ValueError("Expected OSV SBOM source")
+      if not isinstance(result.get("packages"), list):
+         raise ValueError("Missing OSV package inventory; use --all-packages")
+      for raw_entry in cast(list[object], result.get("packages")):
+         entry = cast(OsvEntry, raw_entry)
+         if not isinstance(raw_entry, dict) or not isinstance(entry.get("package"), dict):
+            raise ValueError("Malformed OSV package")
+         package = cast(dict[str, str], entry.get("package"))
+         if package.get("ecosystem") != "Maven" or not all(isinstance(package.get(k), str) and package[k] for k in ("name", "version")):
+            raise ValueError("Invalid OSV Maven package coordinate")
+         if "vulnerabilities" in entry and not isinstance(entry["vulnerabilities"], list):
+            raise ValueError("Malformed OSV vulnerabilities")
+         scanned[(package["name"], package["version"])] += 1
+   if scanned != projected:
+      raise ValueError("OSV --all-packages inventory differs from selected Maven graph")
+   return len(expected)
 
 
-def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("resolved", type=Path)
-    parser.add_argument("bom", type=Path)
-    parser.add_argument("trivy", type=Path, nargs="?")
-    parser.add_argument("--osv", type=Path)
-    args = parser.parse_args()
-    expected = resolved(args.resolved.read_text(encoding="utf-8"))
-    count = check(expected,
-                  json.loads(args.bom.read_text(encoding="utf-8")),
-                  json.loads(args.trivy.read_text(encoding="utf-8")) if args.trivy else OMITTED)
-    if args.osv:
-        check_osv(expected, json.loads(args.osv.read_text(encoding="utf-8")))
-    print(f"Verified {count} Maven runtime dependencies, including the UI frontend.")
+def main() -> None:
+   """Validate the exact evidence files supplied by the required CI job."""
+   parser = argparse.ArgumentParser()
+   parser.add_argument("resolved", type=Path)
+   parser.add_argument("bom", type=Path)
+   parser.add_argument("trivy", type=Path, nargs="?")
+   parser.add_argument("--osv", type=Path)
+   args = parser.parse_args()
+   expected = resolved(args.resolved.read_text(encoding="utf-8"))
+   count = check(expected, json.loads(args.bom.read_text(encoding="utf-8")), json.loads(args.trivy.read_text(encoding="utf-8")) if args.trivy else OMITTED)
+   if args.osv:
+      check_osv(expected, json.loads(args.osv.read_text(encoding="utf-8")))
+   print(f"Verified {count} Maven runtime dependencies, including the UI frontend.")
 
 
 if __name__ == "__main__":
-    main()
+   main()

.github/scripts/check-script-quality.py

@@ -0,0 +1,112 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Fail closed unless every tracked owned script is covered by, and really analyzed by, the quality tools."""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+PYTHON_SUFFIXES = (".py", ".pyi", ".pyw")
+SCRIPT_PATTERN = ".github/scripts/*.py"
+PYRIGHT_CONFIG = ".github"
+JAVASCRIPT_SUFFIXES = (".js", ".cjs", ".mjs", ".jsx", ".ts", ".mts", ".cts", ".tsx")
+# Microsoft's official npm Pyright, restored from package-lock.json by `npm ci --ignore-scripts`.
+PYRIGHT_ENTRY = Path(__file__).resolve().parents[2] / "node_modules" / "pyright" / "index.js"
+
+
+def tracked_files(root: Path) -> list[str]:
+   """List tracked and not-yet-ignored new paths so no source file can silently bypass the gates."""
+   # Fixed Git inventory operation; the root is an argument, never shell input.
+   output = subprocess.run(["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard"], check=True, capture_output=True).stdout.decode("utf-8")  # noqa: S603, S607 -- Resolve Git from the developer/CI PATH; no shell or user-supplied command.
+   return [name for name in output.split("\u0000") if name]
+
+
+def python_scope(tracked: list[str]) -> list[str]:
+   """Return the tracked Python sources, rejecting any outside the one checked script root."""
+   candidates = sorted(name for name in tracked if name.endswith(PYTHON_SUFFIXES))
+   outside = [name for name in candidates if not PurePosixPath(name).full_match(SCRIPT_PATTERN)]
+   if outside:
+      raise ValueError("Tracked Python outside the checked script root: " + ", ".join(outside))
+   if not candidates:
+      raise ValueError("No owned Python scripts selected")
+   return candidates
+
+
+def javascript_scope(root: Path, tracked: list[str]) -> list[str]:
+   """Return tracked JavaScript/TypeScript sources, rejecting any outside the tsconfig include list."""
+   candidates = sorted(name for name in tracked if name.endswith(JAVASCRIPT_SUFFIXES))
+   tsconfig = root / "tsconfig.json"
+   if not tsconfig.is_file():
+      if candidates:
+         raise ValueError("Tracked JavaScript/TypeScript without a tsconfig.json: " + ", ".join(candidates))
+      return []
+   includes: list[str] = json.loads(tsconfig.read_text(encoding="utf-8"))["include"]
+   outside = [name for name in candidates if not any(PurePosixPath(name).full_match(pattern) for pattern in includes)]
+   if outside:
+      raise ValueError("Tracked JavaScript/TypeScript outside the tsconfig include list: " + ", ".join(outside))
+   if not candidates:
+      raise ValueError("No owned JavaScript sources selected")
+   return candidates
+
+
+def run_pyright(root: Path, config: str) -> dict[str, Any]:
+   """Run the locked npm Pyright through Node with JSON output and return its full report."""
+   node = shutil.which("node")
+   if node is None:
+      raise ValueError("Node.js is required to run the locked Pyright")
+   if not PYRIGHT_ENTRY.is_file():
+      raise ValueError(f"Locked Pyright is missing; run npm ci --ignore-scripts ({PYRIGHT_ENTRY})")
+   # Resolved Node and locked entry script; the config is an argument, never shell input.
+   completed = subprocess.run([node, str(PYRIGHT_ENTRY), "-p", config, "--outputjson"], cwd=root, check=False, capture_output=True, text=True, encoding="utf-8")  # noqa: S603 -- Resolved Node and locked entry script; no shell.
+   try:
+      report: dict[str, Any] = json.loads(completed.stdout[completed.stdout.index("{") :])
+      int(report["summary"]["filesAnalyzed"])  # Fail here when the summary shape is missing.
+      report["exitCode"] = completed.returncode
+   except (ValueError, KeyError) as error:
+      raise ValueError(f"Pyright produced no JSON summary (exit {completed.returncode}): {completed.stdout}{completed.stderr}") from error
+   return report
+
+
+def check_pyright_report(report: dict[str, Any], expected: int) -> None:
+   """Require the analyzed-file count to match the selected sources, with no errors or warnings."""
+   summary = report["summary"]
+   analyzed = summary["filesAnalyzed"]
+   if analyzed == 0 or analyzed != expected:
+      raise ValueError(f"Pyright analyzed {analyzed} files, expected {expected}")
+   if summary["errorCount"] or summary["warningCount"]:
+      details = [f"{item['file']}: {item['message']}" for item in report["generalDiagnostics"]]
+      raise ValueError("Pyright reported findings:\n" + "\n".join(details))
+   if report["exitCode"] != 0:
+      raise ValueError(f"Pyright exited {report['exitCode']} despite a clean summary")
+
+
+def run_ruff(root: Path, arguments: list[str], sources: list[str]) -> None:
+   """Run Ruff on the explicit source list so no selected file can be skipped."""
+   # Fixed interpreter module invocation; paths are arguments, never shell input.
+   if subprocess.run([sys.executable, "-m", "ruff", *arguments, "--no-cache", *sources], cwd=root, check=False).returncode != 0:  # noqa: S603 -- Fixed interpreter and module; no shell.
+      raise ValueError("Ruff " + " ".join(arguments) + " failed")
+
+
+def main() -> None:
+   """Verify scope, then Ruff format/lint and strict Pyright with a positive analyzed count."""
+   root = Path(__file__).resolve().parents[2]
+   tracked = tracked_files(root)
+   sources = python_scope(tracked)
+   javascript = javascript_scope(root, tracked)
+   run_ruff(root, ["format", "--check"], sources)
+   run_ruff(root, ["check"], sources)
+   report = run_pyright(root, PYRIGHT_CONFIG)
+   check_pyright_report(report, len(sources))
+   print(f"Script quality verified: {len(sources)} Python scripts analyzed by Ruff and Pyright, {len(javascript)} JavaScript files in tsconfig scope")
+
+
+if __name__ == "__main__":
+   try:
+      main()
+   except (ValueError, OSError, subprocess.CalledProcessError) as error:
+      print(str(error), file=sys.stderr)
+      sys.exit(1)

.github/scripts/check-source-headers.py

@@ -0,0 +1,130 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Check leading notices in explicitly owned, Git-tracked source families."""
+
+import fnmatch
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def selected(name: str, policy: dict[str, Any]) -> bool:
+   """Select owned paths, honoring documented exact/pattern exclusions first."""
+   if any(fnmatch.fnmatchcase(name, item["pattern"]) for item in policy["exclusions"]):
+      return False
+   return any(fnmatch.fnmatchcase(name, pattern) for pattern in policy["includes"])
+
+
+def leading_comments(text: str, style: str) -> str:  # noqa: PLR0912 -- Each recognized leading-comment syntax has a distinct fail-closed branch.
+   """Read comments only, preserving required interpreter/XML directive ordering."""
+   text = text.removeprefix("\ufeff")
+   if text.startswith("<?xml"):
+      declaration = re.match(r"<\?xml[^?]*\?>", text)
+      if style != "xml" or declaration is None:
+         raise ValueError("Invalid XML declaration")
+      text = text[declaration.end() :]
+   elif text.startswith("#!"):
+      if style not in ("hash", "powershell", "slash"):
+         raise ValueError("Unexpected interpreter directive")
+      text = text.partition("\n")[2]
+   while re.match(r"#Requires\b", text, re.IGNORECASE):
+      if style != "powershell":
+         raise ValueError("Unexpected PowerShell directive")
+      text = text.partition("\n")[2]
+   comments: list[str] = []
+   while text.strip():
+      text = text.lstrip()
+      if text.startswith("<?xml") or re.match(r"#!|#Requires\b", text, re.IGNORECASE):
+         raise ValueError("Required declaration must precede the notice")
+      if style in ("hash", "powershell") and text.startswith("#"):
+         line, _, text = text.partition("\n")
+         comments.append(line[1:])
+      elif style == "slash" and text.startswith("//"):
+         line, _, text = text.partition("\n")
+         comments.append(line[2:])
+      elif (style == "slash" and text.startswith("/*")) or (style == "xml" and text.startswith("<!--")) or (style == "powershell" and text.startswith("<#")):
+         opening, closing = {"slash": ("/*", "*/"), "xml": ("<!--", "-->"), "powershell": ("<#", "#>")}[style]
+         body, separator, rest = text[len(opening) :].partition(closing)
+         if not separator:
+            raise ValueError("Unterminated leading comment")
+         comments.append(body)
+         text = rest
+      else:
+         break
+   return "\n".join(re.sub(r"^\s*[*~]\s?", "", line).strip() for line in "\n".join(comments).splitlines())
+
+
+def check_notice(name: str, text: str, policy: dict[str, Any]) -> None:
+   """Require an approved holder/license pair in real leading comment syntax."""
+   suffix = Path(name).suffix
+   style = policy["styles"].get(suffix)
+   if Path(name).name.startswith("Dockerfile."):
+      style = "hash"
+   if style is None:
+      raise ValueError("Selected path has no configured comment syntax")
+   comments = leading_comments(text, style)
+   approved = [item for item in policy["notices"] if any(fnmatch.fnmatchcase(name, pattern) for pattern in item["paths"])]
+   for notice in approved:
+      holder = re.escape(notice["holder"])
+      copyright_pattern = rf"(?m)^Copyright\s+(?:\([cC]\)\s*)?\d{{4}}(?:[-\u2013]\d{{4}})?\.?\s+{holder}(?:\s+\(KofTwentyTwo\))?\.?(?:\s+Licensed under the MIT License \(see LICENSE\)\.)?$"
+      if re.search(copyright_pattern, comments) is None:
+         continue
+      spdx = re.findall(r"(?m)^SPDX-License-Identifier:\s*(\S+)\s*$", comments)
+      if spdx and any(value != notice["license"] for value in spdx):
+         continue
+      apache = all(
+         phrase in comments
+         for phrase in (
+            "Licensed under the Apache License, Version 2.0",
+            "you may not use this file except in compliance with the License.",
+            "https://www.apache.org/licenses/LICENSE-2.0",
+            "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND",
+            "limitations under the License.",
+         )
+      )
+      if suffix == ".java" and not apache:
+         continue
+      if notice["license"] in spdx or (notice["license"] == "Apache-2.0" and apache):
+         return
+   raise ValueError("Missing or mismatched leading copyright/license notice")
+
+
+def check_repository(root: Path, policy: dict[str, Any]) -> int:
+   """Check tracked sources without scanning build outputs or executing source."""
+   # Fixed Git inventory operation; paths are arguments, never shell input.
+   tracked = subprocess.run(["git", "-C", str(root), "ls-files", "-z"], check=True, capture_output=True).stdout.decode("utf-8").split("\u0000")  # noqa: S603, S607 -- Resolve Git from the developer/CI PATH; no shell or user-supplied command.
+   failures: list[str] = []
+   count = 0
+   for name in tracked:
+      if not name or not selected(name, policy):
+         continue
+      count += 1
+      try:
+         check_notice(name, (root / name).read_text(encoding="utf-8-sig"), policy)
+      except (ValueError, OSError) as error:
+         failures.append(f"{name}: {error}")
+   if count == 0:
+      raise ValueError("No owned source files selected")
+   if failures:
+      raise ValueError("\n".join(failures))
+   return count
+
+
+def main() -> None:
+   """Load the repository-specific reviewed scope and fail CI on a bad notice."""
+   root = Path(__file__).resolve().parents[2]
+   policy = json.loads((root / ".github/source-headers.json").read_text(encoding="utf-8"))
+   count = check_repository(root, policy)
+   print(f"Leading source notices verified: {count} tracked files")
+
+
+if __name__ == "__main__":
+   try:
+      main()
+   except (ValueError, OSError, subprocess.CalledProcessError) as error:
+      print(str(error), file=sys.stderr)
+      sys.exit(1)

.github/scripts/test-maven-inventory.py

@@ -1,105 +1,118 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 """Synthetic regressions for missing, incorrect and empty scanner inventories."""
+
 import copy
 import importlib.util
-from pathlib import Path
-import sys
-import subprocess
-import tempfile
 import json
+import subprocess
+import sys
+import tempfile
 import unittest
-
+from pathlib import Path
+from typing import Any, cast, override
 
 sys.dont_write_bytecode = True
 spec = importlib.util.spec_from_file_location("inventory", Path(__file__).with_name("check-maven-inventory.py"))
+assert spec is not None and spec.loader is not None
 inventory = importlib.util.module_from_spec(spec)
 spec.loader.exec_module(inventory)
 
 
 class InventoryTests(unittest.TestCase):
-    def setUp(self):
-        self.expected = {(name, "2.4.240" if name == "com.h2database:h2" else "1.0") for name in inventory.REQUIRED} | {("org.jspecify:jspecify", "1.0.0")}
-        self.text = "The following files have been resolved:\n" + "\n".join(
-            f"   {name}:jar:{version}:runtime\x1b[36m -- module example\x1b[m" for name, version in self.expected)
-        self.bom = {"bomFormat": "CycloneDX", "components": [
-            {"purl": "pkg:maven/" + name.replace(":", "/") + "@" + version + "?type=jar"}
-            for name, version in self.expected]}
-        self.trivy = {"Results": [{"Packages": [{"Name": n, "Version": v} for n, v in self.expected], "Vulnerabilities": []}]}
+   """Exercise selected dependency coverage using isolated synthetic reports."""
 
-    def test_complete_graph_without_findings_passes(self):
-        self.assertEqual(self.expected, inventory.resolved(self.text))
-        self.assertEqual(6, inventory.check(self.expected, self.bom, self.trivy))
+   @override
+   def setUp(self) -> None:
+      """Create isolated synthetic evidence with cleanup after each test."""
+      self.expected = {(name, "2.4.240" if name == "com.h2database:h2" else "1.0") for name in inventory.REQUIRED} | {("org.jspecify:jspecify", "1.0.0")}
+      self.text = "The following files have been resolved:\n" + "\n".join(f"   {name}:jar:{version}:runtime\x1b[36m -- module example\x1b[m" for name, version in self.expected)
+      self.bom: dict[str, Any] = {"bomFormat": "CycloneDX", "components": [{"purl": "pkg:maven/" + name.replace(":", "/") + "@" + version + "?type=jar"} for name, version in self.expected]}
+      self.trivy: dict[str, Any] = {"Results": [{"Packages": [{"Name": n, "Version": v} for n, v in self.expected], "Vulnerabilities": []}]}
 
-    def test_missing_or_unreviewed_h2_version_fails(self):
-        without_h2 = "\n".join(line for line in self.text.splitlines() if "com.h2database:h2:" not in line)
-        for text in (without_h2, self.text.replace("2.4.240", "2.3.232"), self.text.replace("2.4.240", "2.4.241"),
-                     self.text + "\ncom.h2database:h2:jar:2.3.232:runtime"):
-            with self.subTest(text=text), self.assertRaises(ValueError):
-                inventory.resolved(text)
+   def test_complete_graph_without_findings_passes(self) -> None:
+      """Verify complete graph without findings passes."""
+      self.assertEqual(self.expected, inventory.resolved(self.text))
+      self.assertEqual(6, inventory.check(self.expected, self.bom, self.trivy))
 
-    def test_missing_frontend_and_empty_maven_fail(self):
-        for text in ("", "\n".join(line for line in self.text.splitlines() if "qqq-frontend-next" not in line)):
-            with self.assertRaises(ValueError):
-                inventory.resolved(text)
+   def test_missing_or_unreviewed_h2_version_fails(self) -> None:
+      """Verify missing or unreviewed h2 version fails."""
+      without_h2 = "\n".join(line for line in self.text.splitlines() if "com.h2database:h2:" not in line)
+      for text in (without_h2, self.text.replace("2.4.240", "2.3.232"), self.text.replace("2.4.240", "2.4.241"), self.text + "\ncom.h2database:h2:jar:2.3.232:runtime"):
+         with self.subTest(text=text), self.assertRaises(ValueError):
+            inventory.resolved(text)
 
-    def test_test_scope_or_test_jar_fails(self):
-        for extra in ("example:test:jar:1:test", "org.junit.jupiter:junit-jupiter:jar:5:runtime"):
-            with self.assertRaises(ValueError):
-                inventory.resolved(self.text + "\n" + extra)
+   def test_missing_frontend_and_empty_maven_fail(self) -> None:
+      """Verify missing frontend and empty maven fail."""
+      for text in ("", "\n".join(line for line in self.text.splitlines() if "qqq-frontend-next" not in line)):
+         with self.assertRaises(ValueError):
+            inventory.resolved(text)
 
-    def test_empty_malformed_or_missing_component_fails(self):
-        for bom in ({}, {"bomFormat": "CycloneDX", "components": []}, {"bomFormat": "CycloneDX", "components": [{}]},
-                    {"bomFormat": "CycloneDX", "components": self.bom["components"][1:]}):
-            with self.assertRaises(ValueError):
-                inventory.check(self.expected, bom)
+   def test_test_scope_or_test_jar_fails(self) -> None:
+      """Verify test scope or test jar fails."""
+      for extra in ("example:test:jar:1:test", "org.junit.jupiter:junit-jupiter:jar:5:runtime"):
+         with self.assertRaises(ValueError):
+            inventory.resolved(self.text + "\n" + extra)
 
-    def test_wrong_selected_version_fails(self):
-        bad = copy.deepcopy(self.trivy)
-        for package in bad["Results"][0]["Packages"]:
-            if package["Name"] == "org.jspecify:jspecify":
-                package["Version"] = "1.0.1"
-        with self.assertRaises(ValueError):
-            inventory.check(self.expected, self.bom, bad)
+   def test_empty_malformed_or_missing_component_fails(self) -> None:
+      """Verify empty malformed or missing component fails."""
+      for bom in cast(tuple[object, ...], ({}, {"bomFormat": "CycloneDX", "components": []}, {"bomFormat": "CycloneDX", "components": [{}]}, {"bomFormat": "CycloneDX", "components": self.bom["components"][1:]})):
+         with self.assertRaises(ValueError):
+            inventory.check(self.expected, bom)
 
-    def test_empty_or_dropped_trivy_package_fails(self):
-        for report in (None, {}, {"Results": []}, {"Results": [{"Packages": self.trivy["Results"][0]["Packages"][1:]}]}):
-            with self.assertRaises(ValueError):
-                inventory.check(self.expected, self.bom, report)
+   def test_wrong_selected_version_fails(self) -> None:
+      """Verify wrong selected version fails."""
+      bad = copy.deepcopy(self.trivy)
+      for package in bad["Results"][0]["Packages"]:
+         if package["Name"] == "org.jspecify:jspecify":
+            package["Version"] = "1.0.1"
+      with self.assertRaises(ValueError):
+         inventory.check(self.expected, self.bom, bad)
 
-    def test_cli_supplied_null_trivy_fails(self):
-        with tempfile.TemporaryDirectory() as temporary:
-            directory = Path(temporary)
-            (directory / "resolved.txt").write_text(self.text, encoding="utf-8")
-            (directory / "bom.json").write_text(json.dumps(self.bom), encoding="utf-8")
-            (directory / "trivy.json").write_text("null", encoding="utf-8")
-            result = subprocess.run([sys.executable, str(Path(inventory.__file__)),
-                                     str(directory / "resolved.txt"), str(directory / "bom.json"),
-                                     str(directory / "trivy.json")], capture_output=True, text=True, check=False)
-            self.assertNotEqual(0, result.returncode)
-            self.assertIn("Expected Trivy report object", result.stderr)
+   def test_empty_or_dropped_trivy_package_fails(self) -> None:
+      """Verify empty or dropped trivy package fails."""
+      for report in cast(tuple[object, ...], (None, {}, {"Results": []}, {"Results": [{"Packages": self.trivy["Results"][0]["Packages"][1:]}]})):
+         with self.assertRaises(ValueError):
+            inventory.check(self.expected, self.bom, report)
 
-    def osv(self):
-        return {"results": [{"source": {"path": "/src/printing.cdx.json", "type": "sbom"}, "packages": [
-            {"package": {"name": name.split(":", 1)[1], "version": version, "ecosystem": "Maven"}}
-            for name, version in self.expected]}]}
+   def test_cli_supplied_null_trivy_fails(self) -> None:
+      """Verify cli supplied null trivy fails."""
+      with tempfile.TemporaryDirectory() as temporary:
+         directory = Path(temporary)
+         (directory / "resolved.txt").write_text(self.text, encoding="utf-8")
+         (directory / "bom.json").write_text(json.dumps(self.bom), encoding="utf-8")
+         (directory / "trivy.json").write_text("null", encoding="utf-8")
+         assert inventory.__file__ is not None
+         result = subprocess.run([sys.executable, str(Path(inventory.__file__)), str(directory / "resolved.txt"), str(directory / "bom.json"), str(directory / "trivy.json")], capture_output=True, text=True, check=False)  # noqa: S603 -- Execute this interpreter and the fixed sibling guard using synthetic paths, without a shell.
+         self.assertNotEqual(0, result.returncode)
+         self.assertIn("Expected Trivy report object", result.stderr)
 
-    def test_osv_all_clean_packages_pass_without_vulnerabilities(self):
-        self.assertEqual(6, inventory.check_osv(self.expected, self.osv()))
+   def osv(self) -> dict[str, Any]:
+      """Build a clean OSV fixture whose identity matches the selected graph."""
+      return {"results": [{"source": {"path": "/src/printing.cdx.json", "type": "sbom"}, "packages": [{"package": {"name": name.split(":", 1)[1], "version": version, "ecosystem": "Maven"}} for name, version in self.expected]}]}
 
-    def test_osv_missing_malformed_or_partial_evidence_fails(self):
-        partial = self.osv()
-        partial["results"][0]["packages"].pop()
-        wrong = self.osv()
-        wrong["results"][0]["packages"][0]["package"]["version"] = "wrong"
-        duplicate = self.osv()
-        duplicate["results"][0]["packages"].append(duplicate["results"][0]["packages"][0])
-        for report in (None, {}, [], {"results": None}, {"results": []}, {"results": [{}]}, partial, wrong, duplicate):
-            with self.subTest(report=report), self.assertRaises(ValueError):
-                inventory.check_osv(self.expected, report)
+   def test_osv_all_clean_packages_pass_without_vulnerabilities(self) -> None:
+      """Verify osv all clean packages pass without vulnerabilities."""
+      self.assertEqual(6, inventory.check_osv(self.expected, self.osv()))
 
-    def test_osv_ambiguous_group_projection_fails(self):
-        with self.assertRaises(ValueError):
-            inventory.check_osv(self.expected | {("other:jspecify", "1.0.0")}, self.osv())
+   def test_osv_missing_malformed_or_partial_evidence_fails(self) -> None:
+      """Verify osv missing malformed or partial evidence fails."""
+      partial = self.osv()
+      partial["results"][0]["packages"].pop()
+      wrong = self.osv()
+      wrong["results"][0]["packages"][0]["package"]["version"] = "wrong"
+      duplicate = self.osv()
+      duplicate["results"][0]["packages"].append(duplicate["results"][0]["packages"][0])
+      for report in cast(tuple[object, ...], (None, {}, [], {"results": None}, {"results": []}, {"results": [{}]}, partial, wrong, duplicate)):
+         with self.subTest(report=report), self.assertRaises(ValueError):
+            inventory.check_osv(self.expected, report)
+
+   def test_osv_ambiguous_group_projection_fails(self) -> None:
+      """Verify osv ambiguous group projection fails."""
+      with self.assertRaises(ValueError):
+         inventory.check_osv(self.expected | {("other:jspecify", "1.0.0")}, self.osv())
 
 
 if __name__ == "__main__":
-    unittest.main()
+   unittest.main()

.github/scripts/test-scan-gates.py

@@ -1,89 +1,107 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 """Exercise the exact CI guards using synthetic evidence only."""
+
 import contextlib
 import copy
-import io
 import importlib.util
+import io
 import json
-from pathlib import Path
 import sys
 import tempfile
 import unittest
-
+from pathlib import Path
+from types import ModuleType
+from typing import Any, override
 
 sys.dont_write_bytecode = True
 
 
-def load(name):
-    spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
+def load(name: str) -> ModuleType:
+   """Load the real sibling guard for synthetic evidence tests."""
+   spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
+   assert spec is not None and spec.loader is not None
+   module = importlib.util.module_from_spec(spec)
+   spec.loader.exec_module(module)
+   return module
 
 
 codeql = load("check-codeql-sarif")
 
 
 class SarifTests(unittest.TestCase):
-    def setUp(self):
-        self.temporary = tempfile.TemporaryDirectory()
-        self.addCleanup(self.temporary.cleanup)
-        self.directory = Path(self.temporary.name)
-        self.report = {"version": "2.1.0", "runs": [{"tool": {"driver": {"name": "CodeQL", "rules": [{"id": "synthetic", "properties": {"security-severity": "8.0"}}]}}, "results": []}]}
+   """Reject incomplete SARIF evidence and preserve severity enforcement."""
 
-    def save(self, report):
-        (self.directory / "java.sarif").write_text(json.dumps(report), encoding="utf-8")
+   @override
+   def setUp(self) -> None:
+      """Create isolated synthetic evidence with cleanup after each test."""
+      self.temporary = tempfile.TemporaryDirectory()
+      self.addCleanup(self.temporary.cleanup)
+      self.directory = Path(self.temporary.name)
+      self.report: dict[str, Any] = {"version": "2.1.0", "runs": [{"tool": {"driver": {"name": "CodeQL", "rules": [{"id": "synthetic", "properties": {"security-severity": "8.0"}}]}}, "results": []}]}
 
-    def test_clean_report_with_zero_findings_passes(self):
-        self.save(self.report)
-        self.assertFalse(codeql.check(self.directory, "java-kotlin", 7))
+   def save(self, report: object) -> None:
+      """Write the test body as SARIF without validating it first."""
+      (self.directory / "java.sarif").write_text(json.dumps(report), encoding="utf-8")
 
-    def test_missing_report_or_wrong_language_fails(self):
-        with self.assertRaises(ValueError):
-            codeql.check(self.directory, "java-kotlin", 7)
-        self.save(self.report)
-        with self.assertRaises(ValueError):
-            codeql.check(self.directory, "csharp", 7)
+   def test_clean_report_with_zero_findings_passes(self) -> None:
+      """Verify clean report with zero findings passes."""
+      self.save(self.report)
+      self.assertFalse(codeql.check(self.directory, "java-kotlin", 7))
 
-    def test_empty_or_malformed_report_fails(self):
-        for text in ["", "{", "null", "[]"]:
-            with self.subTest(text=text):
-                (self.directory / "java.sarif").write_text(text)
-                with self.assertRaises((ValueError, AttributeError)):
-                    codeql.check(self.directory, "java-kotlin", 7)
+   def test_missing_report_or_wrong_language_fails(self) -> None:
+      """Verify missing report or wrong language fails."""
+      with self.assertRaises(ValueError):
+         codeql.check(self.directory, "java-kotlin", 7)
+      self.save(self.report)
+      with self.assertRaises(ValueError):
+         codeql.check(self.directory, "csharp", 7)
 
-    def test_missing_runs_tool_rules_or_results_fails(self):
-        variants = [{"version": "2.1.0"}, {"version": "2.1.0", "runs": []}]
-        for field in ["tool", "results"]:
-            bad = copy.deepcopy(self.report)
-            del bad["runs"][0][field]
-            variants.append(bad)
-        bad = copy.deepcopy(self.report)
-        bad["runs"][0]["tool"]["driver"]["rules"] = []
-        variants.append(bad)
-        for bad in variants:
-            with self.subTest(report=bad):
-                self.save(bad)
-                with self.assertRaises(ValueError):
-                    codeql.check(self.directory, "java-kotlin", 7)
+   def test_empty_or_malformed_report_fails(self) -> None:
+      """Verify empty or malformed report fails."""
+      for text in ["", "{", "null", "[]"]:
+         with self.subTest(text=text):
+            (self.directory / "java.sarif").write_text(text)
+            with self.assertRaises((ValueError, AttributeError)):
+               codeql.check(self.directory, "java-kotlin", 7)
 
-    def test_high_finding_blocks_and_unknown_rule_fails(self):
-        self.report["runs"][0]["results"] = [{"ruleId": "synthetic"}]
-        self.save(self.report)
-        with contextlib.redirect_stdout(io.StringIO()):
-            self.assertTrue(codeql.check(self.directory, "java-kotlin", 7))
-        self.report["runs"][0]["results"] = [{"ruleId": "missing"}]
-        self.save(self.report)
-        with self.assertRaises(ValueError):
-            codeql.check(self.directory, "java-kotlin", 7)
+   def test_missing_runs_tool_rules_or_results_fails(self) -> None:
+      """Verify missing runs tool rules or results fails."""
+      variants: list[dict[str, Any]] = [{"version": "2.1.0"}, {"version": "2.1.0", "runs": []}]
+      for field in ["tool", "results"]:
+         bad = copy.deepcopy(self.report)
+         del bad["runs"][0][field]
+         variants.append(bad)
+      bad = copy.deepcopy(self.report)
+      bad["runs"][0]["tool"]["driver"]["rules"] = []
+      variants.append(bad)
+      for bad in variants:
+         with self.subTest(report=bad):
+            self.save(bad)
+            with self.assertRaises(ValueError):
+               codeql.check(self.directory, "java-kotlin", 7)
 
-    def test_failed_invocation_and_invalid_threshold_fail(self):
-        self.report["runs"][0]["invocations"] = [{"executionSuccessful": False}]
-        self.save(self.report)
-        with self.assertRaises(ValueError):
-            codeql.check(self.directory, "java-kotlin", 7)
-        with self.assertRaises(ValueError):
-            codeql.check(self.directory, "java-kotlin", float("nan"))
+   def test_high_finding_blocks_and_unknown_rule_fails(self) -> None:
+      """Verify high finding blocks and unknown rule fails."""
+      self.report["runs"][0]["results"] = [{"ruleId": "synthetic"}]
+      self.save(self.report)
+      with contextlib.redirect_stdout(io.StringIO()):
+         self.assertTrue(codeql.check(self.directory, "java-kotlin", 7))
+      self.report["runs"][0]["results"] = [{"ruleId": "missing"}]
+      self.save(self.report)
+      with self.assertRaises(ValueError):
+         codeql.check(self.directory, "java-kotlin", 7)
+
+   def test_failed_invocation_and_invalid_threshold_fail(self) -> None:
+      """Verify failed invocation and invalid threshold fail."""
+      self.report["runs"][0]["invocations"] = [{"executionSuccessful": False}]
+      self.save(self.report)
+      with self.assertRaises(ValueError):
+         codeql.check(self.directory, "java-kotlin", 7)
+      with self.assertRaises(ValueError):
+         codeql.check(self.directory, "java-kotlin", float("nan"))
 
 
 if __name__ == "__main__":
-    unittest.main()
+   unittest.main()

.github/scripts/test-script-quality.py

@@ -0,0 +1,238 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Prove the quality gates reject real violations, using private temporary fixtures and the locked tools."""
+
+import importlib.util
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import ModuleType
+from typing import Any, override
+from unittest import mock
+
+sys.dont_write_bytecode = True
+
+ROOT = Path(__file__).resolve().parents[2]
+GOOD_PYTHON = '"""Probe module."""\n\n\ndef add(left: int, right: int) -> int:\n   """Add two integers."""\n   return left + right\n'
+UNUSED_IMPORT_PYTHON = '"""Probe module."""\n\nimport os\n\n\ndef add(left: int, right: int) -> int:\n   """Add two integers."""\n   return left + right\n'
+TWO_SPACE_PYTHON = '"""Probe module."""\n\n\ndef add(left: int, right: int) -> int:\n  """Add two integers."""\n  return left + right\n'
+INCOMPATIBLE_PYTHON = '"""Probe module."""\n\nVALUE: int = "text"\n'
+UNANNOTATED_PYTHON = '"""Probe module."""\n\n\ndef echo(value):\n   """Return the value."""\n   return value\n'
+GOOD_JAVASCRIPT = "export function addNumbers(left, right)\n{\n   return left + right;\n}\n"
+BAD_LAYOUT_JAVASCRIPT = "export function addNumbers(left, right) {\n  return left + right\n}\n"
+GOOD_TYPED_JAVASCRIPT = "/** @type {number} */\nexport const value = 1;\n"
+INCOMPATIBLE_JAVASCRIPT = '/** @type {number} */\nexport const value = "text";\n'
+
+
+def load(name: str) -> ModuleType:
+   """Load the real sibling guard for tests."""
+   spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
+   assert spec is not None and spec.loader is not None
+   module = importlib.util.module_from_spec(spec)
+   spec.loader.exec_module(module)
+   return module
+
+
+guard = load("check-script-quality")
+
+
+def run(command: list[str], cwd: Path, stdin: str | None = None) -> subprocess.CompletedProcess[str]:
+   """Run one real tool invocation without a shell and capture its diagnostics."""
+   return subprocess.run(command, cwd=cwd, input=stdin, check=False, capture_output=True, text=True, encoding="utf-8")  # noqa: S603 -- Fixed tool paths and private temporary arguments; no shell.
+
+
+def ruff(arguments: list[str], source: Path) -> subprocess.CompletedProcess[str]:
+   """Run the locked Ruff with the repository configuration on one private fixture."""
+   return run([sys.executable, "-m", "ruff", *arguments, "--no-cache", "--config", str(ROOT / "ruff.toml"), str(source)], source.parent)
+
+
+class ScopeTests(unittest.TestCase):
+   """Reject tracked sources that fall outside the explicit tool roots."""
+
+   def test_python_outside_script_root_is_rejected(self) -> None:
+      """Reject a tracked Python file outside the script root instead of letting it disappear."""
+      for stray in ("tools/helper.py", ".github/scripts/nested/helper.py", "helper.pyi"):
+         with self.subTest(stray=stray), self.assertRaisesRegex(ValueError, "outside the checked script root"):
+            guard.python_scope([".github/scripts/check-a.py", stray])
+
+   def test_python_scope_returns_sorted_script_root_and_rejects_empty(self) -> None:
+      """Select only the direct script root, sorted, and reject selecting nothing."""
+      self.assertEqual([".github/scripts/a.py", ".github/scripts/b.py"], guard.python_scope([".github/scripts/b.py", "README.md", ".github/scripts/a.py"]))
+      with self.assertRaisesRegex(ValueError, "No owned Python"):
+         guard.python_scope(["README.md"])
+
+   def test_javascript_requires_tsconfig_include_scope(self) -> None:
+      """Reject tracked JavaScript outside tsconfig include patterns, including .js/.cjs/.ts."""
+      with tempfile.TemporaryDirectory() as name:
+         root = Path(name)
+         (root / "tsconfig.json").write_text(json.dumps({"include": ["tools/**/*.mjs", "eslint.config.mjs"]}), encoding="utf-8")
+         self.assertEqual(["eslint.config.mjs", "tools/a/b.mjs", "tools/c.mjs"], guard.javascript_scope(root, ["tools/c.mjs", "tools/a/b.mjs", "eslint.config.mjs", "README.md"]))
+         for stray in ("src/z.js", "tools/w.cjs", "tools/v.ts", "tools/u.js"):
+            with self.subTest(stray=stray), self.assertRaisesRegex(ValueError, "outside the tsconfig include list"):
+               guard.javascript_scope(root, ["tools/c.mjs", stray])
+         with self.assertRaisesRegex(ValueError, "No owned JavaScript"):
+            guard.javascript_scope(root, ["README.md"])
+
+   def test_javascript_without_tsconfig_is_rejected(self) -> None:
+      """Reject JavaScript in a repository that has no tsconfig."""
+      with tempfile.TemporaryDirectory() as name:
+         root = Path(name)
+         self.assertEqual([], guard.javascript_scope(root, ["README.md"]))
+         with self.assertRaisesRegex(ValueError, "without a tsconfig.json"):
+            guard.javascript_scope(root, ["tools/a.mjs"])
+
+
+class PyrightCountTests(unittest.TestCase):
+   """Reject Pyright reports that analyzed too few files or found anything."""
+
+   @staticmethod
+   def report(analyzed: int, errors: int = 0, warnings: int = 0) -> dict[str, Any]:
+      """Build the exact Pyright JSON shape consumed by the guard."""
+      return {"summary": {"filesAnalyzed": analyzed, "errorCount": errors, "warningCount": warnings}, "generalDiagnostics": [{"file": "x.py", "message": "finding"}] * (errors + warnings), "exitCode": 1 if errors or warnings else 0}
+
+   def test_nonzero_exit_fails_even_with_clean_summary(self) -> None:
+      """Fail a nonzero Pyright exit even when every count is clean."""
+      clean = self.report(4)
+      clean["exitCode"] = 1
+      with self.assertRaisesRegex(ValueError, "exited 1"):
+         guard.check_pyright_report(clean, 4)
+
+   def test_count_must_match_selected_sources(self) -> None:
+      """Fail zero or mismatched analyzed counts even with no diagnostics."""
+      guard.check_pyright_report(self.report(4), 4)
+      for analyzed in (0, 3, 5):
+         with self.subTest(analyzed=analyzed), self.assertRaisesRegex(ValueError, "analyzed"):
+            guard.check_pyright_report(self.report(analyzed), 4)
+
+   def test_errors_and_warnings_fail(self) -> None:
+      """Fail on errors and on warnings at the exact count."""
+      for report in (self.report(4, errors=1), self.report(4, warnings=1)):
+         with self.subTest(report=report), self.assertRaisesRegex(ValueError, "reported findings"):
+            guard.check_pyright_report(report, 4)
+
+
+class RuffProbeTests(unittest.TestCase):
+   """Run the real locked Ruff on bounded private fixtures."""
+
+   def test_compliant_fixture_passes_and_violations_fail(self) -> None:
+      """Pass a compliant control and reject unused imports and wrong indentation."""
+      with tempfile.TemporaryDirectory() as name:
+         probe = Path(name) / "probe.py"
+         probe.write_text(GOOD_PYTHON, encoding="utf-8", newline="\n")
+         self.assertEqual(0, ruff(["check"], probe).returncode)
+         self.assertEqual(0, ruff(["format", "--check"], probe).returncode)
+         probe.write_text(UNUSED_IMPORT_PYTHON, encoding="utf-8", newline="\n")
+         unused = ruff(["check", "--output-format", "concise"], probe)
+         self.assertNotEqual(0, unused.returncode)
+         self.assertIn("F401", unused.stdout)
+         probe.write_text(TWO_SPACE_PYTHON, encoding="utf-8", newline="\n")
+         indented = ruff(["format", "--check"], probe)
+         self.assertNotEqual(0, indented.returncode)
+         self.assertIn("would be reformatted", (indented.stdout + indented.stderr).lower())
+
+
+class PyrightProbeTests(unittest.TestCase):
+   """Run the real locked Pyright with the repository strict settings on private projects."""
+
+   @staticmethod
+   def project(root: Path, include: list[str] | None = None) -> None:
+      """Write the repository Pyright config, without its venv location, into a private project."""
+      config: dict[str, Any] = json.loads((ROOT / ".github/pyrightconfig.json").read_text(encoding="utf-8"))
+      del config["venvPath"], config["venv"]
+      if include is not None:
+         config["include"] = include
+      (root / "pyrightconfig.json").write_text(json.dumps(config), encoding="utf-8")
+
+   def test_compliant_control_passes_and_strict_violations_fail(self) -> None:
+      """Analyze the control once with no findings and reject incompatible and unannotated code."""
+      with tempfile.TemporaryDirectory() as name:
+         root = Path(name)
+         self.project(root)
+         scripts = root / "scripts"
+         scripts.mkdir()
+         probe = scripts / "probe.py"
+         probe.write_text(GOOD_PYTHON, encoding="utf-8", newline="\n")
+         clean = guard.run_pyright(root, ".")
+         self.assertEqual(0, clean["exitCode"])
+         guard.check_pyright_report(clean, 1)
+         clean["exitCode"] = 1
+         with self.assertRaisesRegex(ValueError, "exited 1"):
+            guard.check_pyright_report(clean, 1)
+         probe.write_text(INCOMPATIBLE_PYTHON, encoding="utf-8", newline="\n")
+         report = guard.run_pyright(root, ".")
+         self.assertIn("reportAssignmentType", {item.get("rule") for item in report["generalDiagnostics"]})
+         with self.assertRaisesRegex(ValueError, "reported findings"):
+            guard.check_pyright_report(report, 1)
+         probe.write_text(UNANNOTATED_PYTHON, encoding="utf-8", newline="\n")
+         strict = guard.run_pyright(root, ".")
+         self.assertIn("reportMissingParameterType", {item.get("rule") for item in strict["generalDiagnostics"]})
+
+   def test_missing_locked_pyright_or_node_is_rejected(self) -> None:
+      """Reject a missing locked Pyright entry or Node instead of silently skipping the type gate."""
+      with tempfile.TemporaryDirectory() as name:
+         root = Path(name)
+         with mock.patch.object(guard, "PYRIGHT_ENTRY", root / "missing.js"), self.assertRaisesRegex(ValueError, "Locked Pyright is missing"):
+            guard.run_pyright(root, ".")
+         with mock.patch.object(guard.shutil, "which", return_value=None), self.assertRaisesRegex(ValueError, "Node.js is required"):
+            guard.run_pyright(root, ".")
+
+   def test_zero_analyzed_files_cannot_pass(self) -> None:
+      """Reject an empty include and a hidden-directory root config in the wrapper."""
+      with tempfile.TemporaryDirectory() as name:
+         root = Path(name)
+         scripts = root / ".github" / "scripts"
+         scripts.mkdir(parents=True)
+         (scripts / "probe.py").write_text(GOOD_PYTHON, encoding="utf-8", newline="\n")
+         for include in (["nothing/*.py"], [".github/scripts/*.py"]):
+            self.project(root, include)
+            with self.subTest(include=include), self.assertRaises(ValueError):
+               guard.check_pyright_report(guard.run_pyright(root, "."), 1)
+
+
+class JavaScriptProbeTests(unittest.TestCase):
+   """Run the real locked ESLint and TypeScript on bounded private input."""
+
+   @override
+   def setUp(self) -> None:
+      """Skip only where tsconfig is absent, because the scope guard forbids JavaScript there."""
+      if not (ROOT / "tsconfig.json").is_file():
+         self.skipTest("No JavaScript tooling in this repository")
+      node = shutil.which("node")
+      self.assertIsNotNone(node)
+      self.node = str(node)
+
+   def eslint(self, text: str) -> subprocess.CompletedProcess[str]:
+      """Lint text as an in-scope tool file using the repository configuration."""
+      return run([self.node, str(ROOT / "node_modules/eslint/bin/eslint.js"), "--stdin", "--stdin-filename", "tools/probe.mjs", "--max-warnings", "0", "--format", "json"], ROOT, text)
+
+   def test_eslint_rejects_wrong_layout(self) -> None:
+      """Pass a compliant control and reject K&R braces, two-space indent and a missing semicolon."""
+      good = self.eslint(GOOD_JAVASCRIPT)
+      self.assertEqual(0, good.returncode, good.stdout + good.stderr)
+      bad = self.eslint(BAD_LAYOUT_JAVASCRIPT)
+      self.assertNotEqual(0, bad.returncode)
+      rules = {message["ruleId"] for message in json.loads(bad.stdout)[0]["messages"]}
+      self.assertLessEqual({"@stylistic/brace-style", "@stylistic/semi", "@stylistic/indent"}, rules)
+
+   def test_checked_javascript_rejects_incompatible_assignment(self) -> None:
+      """Reject a real incompatible assignment under the repository strict checkJs settings."""
+      with tempfile.TemporaryDirectory() as name:
+         root = Path(name)
+         (root / "tsconfig.json").write_text(json.dumps({"extends": (ROOT / "tsconfig.json").as_posix(), "compilerOptions": {"typeRoots": [(ROOT / "node_modules/@types").as_posix()]}, "include": ["probe.mjs"]}), encoding="utf-8")
+         tsc = [self.node, str(ROOT / "node_modules/typescript/bin/tsc"), "-p", str(root / "tsconfig.json")]
+         (root / "probe.mjs").write_text(GOOD_TYPED_JAVASCRIPT, encoding="utf-8", newline="\n")
+         good = run(tsc, root)
+         self.assertEqual(0, good.returncode, good.stdout + good.stderr)
+         (root / "probe.mjs").write_text(INCOMPATIBLE_JAVASCRIPT, encoding="utf-8", newline="\n")
+         bad = run(tsc, root)
+         self.assertNotEqual(0, bad.returncode)
+         self.assertIn("TS2322", bad.stdout)
+
+
+if __name__ == "__main__":
+   unittest.main()

.github/scripts/test-source-headers.py

@@ -0,0 +1,160 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Exercise notice parsing, provenance, scope and real Git inventory rejection."""
+
+import importlib.util
+import json
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from typing import Any
+
+SPEC = importlib.util.spec_from_file_location("headers", Path(__file__).with_name("check-source-headers.py"))
+assert SPEC is not None and SPEC.loader is not None
+HEADERS = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(HEADERS)
+POLICY = json.loads(Path(__file__).parents[1].joinpath("source-headers.json").read_text(encoding="utf-8"))
+MIT = "Copyright (c) 2026 James Maes\nSPDX-License-Identifier: MIT"
+APACHE = """Copyright (C) 2021-2025. Kingsrook, LLC
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License."""
+
+
+def fixture_policy(holder: str = "James Maes", license_id: str = "MIT") -> dict[str, Any]:
+   """Use the production styles with a small explicit owned fixture scope."""
+   return {"includes": ["src/*"], "exclusions": [], "styles": POLICY["styles"], "notices": [{"holder": holder, "license": license_id, "paths": ["src/*"]}]}
+
+
+class HeaderTests(unittest.TestCase):
+   """Ensure policy failures cannot pass through text-only copyright searches."""
+
+   def test_each_real_comment_syntax(self) -> None:
+      """Recognize hash, slash, block and XML notices in their own languages."""
+      for name, text in (
+         ("src/a.py", "# " + MIT.replace("\n", "\n# ") + "\nprint(1)"),
+         ("src/a.cs", "// " + MIT.replace("\n", "\n// ") + "\nclass A {}"),
+         ("src/a.mjs", "/*\n * " + MIT.replace("\n", "\n * ") + "\n */\nexport {};"),
+         ("src/a.xml", "<!--\n" + MIT + "\n-->\n<root/>"),
+         ("src/a.ps1", "<#\n" + MIT + "\n#>\nWrite-Output 1"),
+      ):
+         with self.subTest(name=name):
+            HEADERS.check_notice(name, text, fixture_policy())
+
+   def test_year_range_separator_is_hyphen_or_en_dash_only(self) -> None:
+      """Accept a hyphen or en dash between years and reject any other separator."""
+      for separator, accepted in (("-", True), (chr(0x2013), True), ("/", False), (chr(0x2014), False)):
+         text = f"# Copyright 2025{separator}2026 James Maes\n# SPDX-License-Identifier: MIT"
+         with self.subTest(separator=separator):
+            if accepted:
+               HEADERS.check_notice("src/a.py", text, fixture_policy())
+            else:
+               with self.assertRaises(ValueError):
+                  HEADERS.check_notice("src/a.py", text, fixture_policy())
+
+   def test_required_first_lines_and_bom(self) -> None:
+      """Accept shebangs, PowerShell requirements and XML declarations first."""
+      for name, prefix, body in (
+         ("src/a.sh", "#!/bin/sh\n", "# " + MIT.replace("\n", "\n# ")),
+         ("src/a.ps1", "#Requires -Version 7.4\n", "# " + MIT.replace("\n", "\n# ")),
+         ("src/a.xml", '<?xml version="1.0"?>\n', "<!--" + MIT + "--><root/>"),
+         ("src/a.mjs", "#!/usr/bin/env node\n", "/*" + MIT + "*/"),
+      ):
+         with self.subTest(name=name):
+            HEADERS.check_notice(name, "\ufeff" + prefix + body, fixture_policy())
+
+   def test_misordered_required_first_lines_fail(self) -> None:
+      """A notice must not displace an interpreter or XML declaration."""
+      for name, text in (
+         ("src/a.sh", "# " + MIT.replace("\n", "\n# ") + "\n#!/bin/sh"),
+         ("src/a.ps1", "# " + MIT.replace("\n", "\n# ") + "\n#Requires -Version 7.4"),
+         ("src/a.xml", "<!--" + MIT + '--><?xml version="1.0"?><root/>'),
+      ):
+         with self.subTest(name=name), self.assertRaises(ValueError):
+            HEADERS.check_notice(name, text, fixture_policy())
+
+   def test_code_strings_and_late_comments_do_not_count(self) -> None:
+      """Reject docstrings and comments after executable declarations."""
+      for text in ('notice = "' + MIT.replace("\n", "\\n") + '"', '"""' + MIT + '"""', "import os\n# " + MIT.replace("\n", "\n# ")):
+         with self.subTest(text=text), self.assertRaises(ValueError):
+            HEADERS.check_notice("src/a.py", text, fixture_policy())
+
+   def test_wrong_syntax_and_unterminated_comments_fail(self) -> None:
+      """Notice text alone is insufficient without a complete language comment."""
+      for text in ("# " + MIT, "/*" + MIT, 'string text = "' + MIT + '";'):
+         with self.subTest(text=text), self.assertRaises(ValueError):
+            HEADERS.check_notice("src/a.cs", text, fixture_policy())
+      with self.assertRaises(ValueError):
+         HEADERS.check_notice("src/a.py", "<#" + MIT + "#>", fixture_policy())
+
+   def test_wrong_holder_or_license_and_conflicting_spdx_fail(self) -> None:
+      """Do not conflate repository licenses or accept conflicting identifiers."""
+      for text in (MIT.replace("James Maes", "Someone Else"), MIT.replace("MIT", "Apache-2.0"), MIT + "\nSPDX-License-Identifier: Apache-2.0", MIT.splitlines()[0]):
+         with self.subTest(text=text), self.assertRaises(ValueError):
+            HEADERS.check_notice("src/a.cs", "/*" + text + "*/", fixture_policy())
+
+   def test_complete_legacy_apache_without_spdx(self) -> None:
+      """Retain valid legacy year ranges and complete Apache notices."""
+      policy = fixture_policy("Kingsrook, LLC", "Apache-2.0")
+      HEADERS.check_notice("src/A.java", "/*" + APACHE + "*/\nclass A {}", policy)
+      HEADERS.check_notice("src/a.xml", "<!--" + APACHE + "--><root/>", policy)
+
+   def test_java_requires_full_apache_block(self) -> None:
+      """An abbreviated SPDX-only Java notice cannot replace scoped convention."""
+      policy = fixture_policy("Kingsrook, LLC", "Apache-2.0")
+      for notice in ("Copyright 2026 Kingsrook, LLC\nSPDX-License-Identifier: Apache-2.0", APACHE.replace("limitations under the License.", "")):
+         with self.subTest(notice=notice), self.assertRaises(ValueError):
+            HEADERS.check_notice("src/A.java", "/*" + notice + "*/", policy)
+
+   def test_virtual_agent_provenance_is_path_scoped(self) -> None:
+      """Only the owned virtual-agent family may use its existing QRun.IO holder."""
+      policy = fixture_policy()
+      policy["notices"].append({"holder": "QRun.IO, Inc.", "license": "MIT", "paths": ["tools/virtual-agent/*"]})
+      text = "/*Copyright 2026 QRun.IO, Inc. Licensed under the MIT License (see LICENSE).\nSPDX-License-Identifier: MIT*/"
+      HEADERS.check_notice("tools/virtual-agent/a.mjs", text, policy)
+      with self.assertRaises(ValueError):
+         HEADERS.check_notice("src/a.mjs", text, policy)
+
+   def test_current_scope_and_documented_exclusions(self) -> None:
+      """New scripts enter the guard; data, generated and upstream files do not."""
+      self.assertTrue(HEADERS.selected(".github/scripts/new-tool.py", POLICY))
+      self.assertTrue(HEADERS.selected(".github/workflows/new-check.yml", POLICY))
+      for name in (".mvn/wrapper/MavenWrapperDownloader.java", "mvnw", "schemas/new.json", "src/main/resources/openapi/new.yaml", "src/test/resources/openapi/old.yaml", "src/generated/Example.cs", "src/Example/obj/Generated.cs", "packages.lock.json"):
+         with self.subTest(name=name):
+            self.assertFalse(HEADERS.selected(name, POLICY))
+      self.assertTrue(all(item["reason"].strip() for item in POLICY["exclusions"]))
+
+   def test_guard_sources_match_this_repository_provenance(self) -> None:
+      """Check copied guard files against local policy even before Git staging."""
+      for filename in ("check-source-headers.py", "test-source-headers.py"):
+         path = Path(__file__).with_name(filename)
+         name = ".github/scripts/" + filename
+         self.assertTrue(HEADERS.selected(name, POLICY))
+         HEADERS.check_notice(name, path.read_text(encoding="utf-8"), POLICY)
+
+   def test_real_git_inventory_rejects_missing_tracked_header(self) -> None:
+      """A tracked new source fails while untracked generated output is ignored."""
+      with tempfile.TemporaryDirectory() as directory:
+         root = Path(directory)
+         subprocess.run(["git", "init", "-q", str(root)], check=True)  # noqa: S603, S607 -- Fixed Git command in the owned temporary test directory.
+         root.joinpath("src").mkdir()
+         source = root / "src/a.py"
+         source.write_text("print(1)", encoding="utf-8")
+         subprocess.run(["git", "-C", str(root), "add", "--", "src/a.py"], check=True)  # noqa: S603, S607 -- Fixed synthetic path; never a shell command.
+         with self.assertRaisesRegex(ValueError, "src/a.py"):
+            HEADERS.check_repository(root, fixture_policy())
+         source.write_text("# " + MIT.replace("\n", "\n# ") + "\nprint(1)", encoding="utf-8")
+         root.joinpath("src/untracked.py").write_text("print(2)", encoding="utf-8")
+         self.assertEqual(1, HEADERS.check_repository(root, fixture_policy()))
+
+
+if __name__ == "__main__":
+   unittest.main()

.github/source-headers.json

@@ -0,0 +1,111 @@
+{
+  "description": "Scope of the reviewed 2026-11-01 owned-source notice pass. Python fnmatch patterns match slash-containing relative paths. Native C# IDE0073 and full Java Apache conventions remain in force.",
+  "includes": [
+    ".github/*.yml",
+    ".github/*.yaml",
+    ".github/scripts/*.py",
+    "pom.xml",
+    "checkstyle/*.xml",
+    "dev/*.ps1",
+    "dev/*.cs",
+    "dev/*.csproj",
+    "dev/*.java",
+    "dev/*.sh",
+    "dev/*.yaml",
+    "dev/*.xml",
+    "dev/Dockerfile.*",
+    "dev/native-auth/Dockerfile.*",
+    "src/main/java/*.java",
+    "src/test/java/*.java",
+    "src/test/resources/log4j2-test.xml"
+  ],
+  "exclusions": [
+    {
+      "pattern": "*.json",
+      "reason": "Schema, fixtures, manifests and lock data: repository LICENSE/NOTICE, no comments."
+    },
+    {
+      "pattern": "*.lock",
+      "reason": "Dependency lock data, not owned executable source."
+    },
+    {
+      "pattern": "*/generated/*",
+      "reason": "Explicit generated-code directory."
+    },
+    {
+      "pattern": "*/bin/*",
+      "reason": "Generated build output."
+    },
+    {
+      "pattern": "*/obj/*",
+      "reason": "Generated build output."
+    },
+    {
+      "pattern": "*/node_modules/*",
+      "reason": "Third-party dependency output."
+    },
+    {
+      "pattern": ".mvn/*",
+      "reason": "Upstream Maven wrapper provenance."
+    },
+    {
+      "pattern": "mvnw*",
+      "reason": "Upstream Maven wrapper provenance."
+    },
+    {
+      "pattern": "Assets/Legal/*",
+      "reason": "Byte-exact third-party legal files."
+    },
+    {
+      "pattern": "src/main/resources/*",
+      "reason": "Bundled font/legal assets and OpenAPI schema data."
+    },
+    {
+      "pattern": "src/test/resources/openapi/*",
+      "reason": "Historical contract schema fixtures."
+    },
+    {
+      "pattern": "*.slnx",
+      "reason": "Solution metadata outside the completed source-header pass; root LICENSE/NOTICE applies."
+    },
+    {
+      "pattern": "*.manifest",
+      "reason": "Application activation metadata outside this pass; root LICENSE/NOTICE applies."
+    },
+    {
+      "pattern": "*.runsettings",
+      "reason": "Test runner metadata outside this pass; root LICENSE/NOTICE applies."
+    },
+    {
+      "pattern": ".editorconfig",
+      "reason": "Style configuration outside this pass; root LICENSE/NOTICE applies."
+    }
+  ],
+  "styles": {
+    ".py": "hash",
+    ".ps1": "powershell",
+    ".psd1": "powershell",
+    ".sh": "hash",
+    ".yml": "hash",
+    ".yaml": "hash",
+    ".cs": "slash",
+    ".java": "slash",
+    ".mjs": "slash",
+    ".js": "slash",
+    ".xml": "xml",
+    ".props": "xml",
+    ".csproj": "xml",
+    ".wxs": "xml",
+    ".wixproj": "xml",
+    ".xaml": "xml"
+  },
+  "notices": [
+    {
+      "paths": [
+        "*"
+      ],
+      "license": "Apache-2.0",
+      "holder": "Kingsrook, LLC"
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 name: Build and prerelease
 
 on:
@@ -26,13 +29,34 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: QRun-IO/qqq-print-protocol
-          ref: f4f977ca4aa6b749e6a52760eed5e53c99a7704d
+          ref: a26c18c90c7d6102bbe26eb50cbb90fcd1bd46e3
           path: qqq-print-protocol
           persist-credentials: false
-      - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+      - uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
         with:
           distribution: temurin
           java-version: '21'
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: '24'
+          package-manager-cache: false
+      - name: Restore locked Pyright
+        run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: '0.13.6'
+          enable-cache: false
+      - name: Restore locked Python tools
+        run: uv sync --locked
+      - name: Verify script quality gates and rejection paths
+        run: |
+          uv run --locked --no-sync python .github/scripts/test-script-quality.py
+          uv run --locked --no-sync python .github/scripts/check-script-quality.py
+      - name: Verify owned source notices and rejection paths
+        run: |
+          python3 .github/scripts/test-source-headers.py
+          python3 .github/scripts/check-source-headers.py
       - name: Checkstyle, unit tests and HTTP contract tests
         run: bash ./mvnw --batch-mode --no-transfer-progress -Pui-demo verify
       - name: Prepare JAR, POM and checksums

.github/workflows/codeql-analysis.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 # Local copy of KofTwentyTwo/standards at fdf5ed029603c938615a32b1beca3628b8787945 (v0.1.2).
 # Pins, inputs and analysis checks preserved; report validation now fails closed.
 # Static analysis (K22-CI-22): CodeQL with the security-extended suite, failing on

.github/workflows/codeql.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 name: codeql
 on:
   pull_request:

.github/workflows/development.yml

@@ -0,0 +1,67 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+name: development
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      native-auth:
+        description: Run the opt-in, unpublished native-auth candidate qualification
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: development-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  scripts:
+    name: development-scripts (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, windows-latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Analyze and test development scripts
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser -Force
+          Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser -Force
+          Import-Module PSScriptAnalyzer -RequiredVersion 1.25.0
+          Import-Module Pester -RequiredVersion 5.7.1
+          $issues = @(Invoke-ScriptAnalyzer -Path dev -Recurse -Severity Warning,Error)
+          if ($issues.Count) { $issues | Format-Table; throw 'Development script analysis failed.' }
+          $configuration = New-PesterConfiguration
+          $configuration.Run.Path = './dev/tests'
+          $configuration.Run.Exit = $true
+          $configuration.TestRegistry.Enabled = $false
+          Invoke-Pester -Configuration $configuration
+
+  docker:
+    name: development-docker
+    runs-on: ubuntu-24.04
+    timeout-minutes: 50
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Run disposable S3 and network printing smoke tests
+        shell: pwsh
+        run: ./dev/Invoke-Dev.ps1 -Action Test
+      - name: Run opt-in real native provider qualification
+        if: github.event_name == 'workflow_dispatch' && inputs.native-auth
+        shell: pwsh
+        run: ./dev/Invoke-Dev.ps1 -Action Test -ExperimentalNativeAuth

.github/workflows/pr-gates.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 # Pull request gates (K22-CI-01): Conventional Commit title, DCO sign-off, and
 # dependency review, from the shared KofTwentyTwo/standards workflow pinned by SHA
 # (K22-CI-11). Dependabot's github-actions ecosystem keeps the pin current.

.github/workflows/security.yml

@@ -1,3 +1,6 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
 # Local copy of KofTwentyTwo/standards security.yml at
 # fdf5ed029603c938615a32b1beca3628b8787945 (v0.1.2).
 # Scanner pins and security gates are preserved. SCA scans Maven-selected runtime
@@ -62,7 +65,7 @@ jobs:
       # Resolve the actual deployed profile, including frontend assets.
       # Do not restore an Actions cache in this security job.
       - name: Set up Java
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
         with:
           distribution: temurin
           java-version: '21'

.gitignore

@@ -12,3 +12,9 @@ dist/
 *.iml
 .DS_Store
 Thumbs.db
+
+# Local script-quality environments and tool caches.
+.venv/
+node_modules/
+.ruff_cache/
+__pycache__/

.python-version

@@ -0,0 +1 @@
+3.13

CHANGELOG.md

@@ -1,8 +1,122 @@
 # Changelog
 
-## 0.1.4-rc.1 — unreleased
+## Unreleased (0.4.0-SNAPSHOT)
 
-- Use the official Query dog mascot on every built-in PDF and ZPL diagnostic profile, preserving the original artwork and aspect ratio. The full local gate passes 73 tests with zero Checkstyle violations; PDF previews and reconstructed thermal graphics pass visual review. New physical output remains to be confirmed after deployment.
+Printing extension **2.3.0** (additive; wire payload v1 and the agent subprotocol are
+unchanged). 2.1.0 added the record, table-list and text print processes; 2.2.0 added
+`printingRenderToPdf`, the header and footer values on every document and content
+sections; 2.3.0 adds the least-privilege operator catalog/submission/request lookup,
+reported Windows queue-default media (`printer-media-v1`) and the opt-in
+retained-source facade. Clients should offer a feature when its process is in the
+metadata, not by comparing versions. An agent that does not advertise
+`printer-media-v1` stays a three-capability peer and cannot claim a job carrying a
+media selection, whatever extension version it discovers.
+
+- Realtime shutdown now waits, with a bound, for channel workers that are already
+  running before the host's durable state is released. Previously the executor was
+  only told to stop, so a late drain could query a stopped file database and
+  recreate it empty (found as a temporary-directory cleanup error in a full test
+  run).
+
+Observed locally on the merged candidate: full `-Pui-demo verify` 189 reported,
+188 executed, one intentional opt-in workload skip, zero failures/errors, zero
+Checkstyle violations; five consecutive focused realtime runs passed. Hosted CI on
+the final signed head, publication and consumer qualification have not run; no
+physical output is claimed.
+
+- The app's header and footer on every page of every document (record sheets,
+  table lists, text and content pages): app name, title or breadcrumb, server,
+  user and printed-at at the top; the client's footer (e.g. `qqq ui 1.0.1 ·
+  server`), a list's filter and sort, and "Page n of m" at the bottom. Clients
+  send `headerApp`, `headerTitle`, `headerServer`, `headerUser`, `headerPrintedAt`,
+  `footerLeft` and `footerNote`; missing ones default to the instance branding,
+  the session user, the current instant and "QQQ printing".
+- Content documents: `printingPrintText` and `printingRenderToPdf` (`TEXT`) take
+  `sections` (JSON `[{title, lines}]`), a screen's panels without navigation or
+  borders, rendered as headings with their lines wrapped to the page width.
+- Save as PDF: `printingRenderToPdf` renders the document a print would carry -
+  a record sheet (`kind` `RECORD`, `tableName`, `recordId`), a table list (`LIST`,
+  the `printingPrintTableList` values) or a text page (`TEXT`) - and returns it to
+  the caller as the standard process download (`downloadFileName`,
+  `serverFilePath`) instead of queueing a job. No printer is needed; reads enforce
+  the caller's permissions, and a list over the limit says so in
+  `printingMessage`. Clients offer it as "Save as PDF…" in their printer pickers.
+- Print anything: `PrintingRecordProcesses.registerAll(instance)` adds **Print** to
+  every table that can be read one record at a time (call it after the host's
+  tables are in the instance). Hidden tables, tables without a primary key or
+  `TABLE_GET`, and tables carrying `PrintingTableSettings().withPrintable(false)`
+  are skipped.
+- The record sheet now follows the table's metadata: field sections in tier order
+  with their labels, remaining fields under "Other fields", and a summary of each
+  child list (association): its label, row count and first ten rows.
+- New `printingPrintTableList`: a table list (grid) of any readable table with the
+  caller's columns (in order) and widths, filter and sort, either the whole result
+  (`scope` `ALL`, the default: read a thousand rows at a time up to `maxRows`,
+  10,000 by default and at most; a larger result prints its first rows and says
+  so in the header and in `printingMessage`) or the current page (`PAGE`, the
+  filter's skip/limit). Letter or A4; orientation `AUTO` (landscape when the
+  columns need it), portrait or landscape. The header repeats on every page; the
+  page header carries the table, the rows printed of the total, the filter text
+  and the sort, and the footer the table, time, user and "Page n of m".
+  `printingRowCount` reports the matching rows before printing.
+- New `printingPrintText`: any text (a capture of a terminal screen) as a
+  monospace PDF, wrapped and broken across pages.
+- All documents share one page writer with "Page n of m" footers and a running
+  title on later pages. Table and record reads enforce the user's permissions.
+
+## 0.3.1-SNAPSHOT
+
+- Add record printing: `PrintingRecordProcesses.register(instance, table)` adds a
+  **Print** process (`printingPrintRecords_{table}`) to a host table's records and
+  selections. It asks for an approved, exposed PDF printer and a copy count, shows
+  the standard review, then renders each selected record as a Letter record sheet
+  (`PrintingRecordDocuments`: heading, visible non-binary fields with display
+  values, wrapped and continued across pages) and queues one PDF job per record.
+  The queued job IDs are returned in the process value `printingJobIds`.
+- Fix selection actions whose first step is a form (**Print a test page**,
+  **Print a test label** on selected printers, and **Print**): over the UI API the
+  record selection reaches only the init call, so the review answered "No records
+  were selected". The prepare step now keeps the selection as `queryFilterJson`.
+
+## 0.3.0-rc.1 — 2026-10-31
+
+Upgrade the server before the matching Windows connector. Native printing API
+2.0 requires synchronized authenticated WSS; old native clients cannot claim
+without it, and there is no polling fallback. Wire payloads remain v1.
+
+- Add client-initiated realtime WebSocket delivery under native printing API 2.0,
+  with current QQQ session and record permissions revalidated during connection use.
+- Deliver desired state, device commands, inventory, lifecycle events and receipts
+  over the socket; native claims require acknowledged current settings and state.
+- Stream retained documents independently from controls and expose document,
+  concurrency, timing, admission and retention batch limits in native admin forms.
+- Preserve durable job/command identities across reconnects. Installed Windows
+  realtime and physical-output acceptance remain separate from source/test gates.
+
+## 0.2.0-rc.1 — 2026-10-31
+
+- Add native device/table selection actions for pause, resume, disconnect,
+  reconnect, revocation, inventory refresh and queued-job clearing, plus exact
+  owned Windows-job cancellation and bounded command history.
+- Show device presence, desired versus applied control state, related printers,
+  jobs and queue; include connection/control issues in the printing dashboard.
+- Register semantic printing extension `1.0.0` at `/qqq/v1/qbit/printing`, using
+  standard QQQ user sessions and secondary device proof with current native
+  record/process permissions. Legacy bearer transport remains explicit compatibility.
+- Preserve journal/history and distinguish accepted commands from confirmed
+  execution. Shared-core/provider native authentication acceptance and installed
+  candidate qualification remain required before deployment claims.
+- Explicitly enforce current native permissions during selection counts and
+  extraction, including callbacks and query selections. Pass 110 Java tests and
+  25 real .NET client/native QQQ interoperability checks without print jobs,
+  including rejection of legacy enrollment and bound-token downgrade attempts.
+- Reject account-bound device tokens on legacy routes and disable legacy
+  enrollment by default. Legacy-only hosts opt in explicitly; existing unbound
+  devices retain migration compatibility.
+
+## 0.1.4-rc.1 — 2026-10-31
+
+- Use the official Query dog mascot on every built-in PDF and ZPL diagnostic profile, preserving the original artwork and aspect ratio. Full local and hosted gates pass 73 tests with zero Checkstyle violations; PDF previews and reconstructed thermal graphics pass visual review. Local native deployment is accepted; physical output from the updated Query diagnostics remains unconfirmed.
 - Add an authenticated loopback QQQ host that shares durable paired devices/jobs with native screens and retention scheduling, preserving the separate synthetic UI demo.
 - Make native enrollment and test-print execution replay-safe and retain known duplicate-output risk after later failures.
 - Strictly validate print options, inventory formats/status and event bounds before persistence; recheck current queue format support at claim time.
@@ -16,7 +130,8 @@
 - Pin H2 2.4.240 to fix close-time compaction data loss; verify file-backed schema/settings across cold reopens and document closed-backup upgrade qualification.
 - Verify the exact frontend-inclusive runtime inventory in Maven, Trivy and OSV; fail on malformed or incomplete scanner evidence.
 - Include repository LICENSE and NOTICE under META-INF using standard Maven resources; preserve font license, provenance and diagnostic assets.
-- Full local and fresh hosted verification passed 72 tests with zero failures/errors/skips and Checkstyle violations, including incompatible S3 bindings, multiline prefix retargeting, retry accounting and inline document compatibility. Actual cross-platform refusal preserves objects and accounting with zero SDK requests. Required build/security/CodeQL/dependency gates pass with the approved scoped H2 record. The exact CI artifact passed isolated graceful/cold-restart checks and local paired-host cutover with native authentication, preserved records, automatic connector reconnection and 365-day retention. No live S3 migration or remote deployment is claimed.
+- The S3 safeguard checkpoint passed 72 tests with zero failures/errors/skips and Checkstyle violations, including incompatible S3 bindings, multiline prefix retargeting, retry accounting and inline document compatibility. Actual cross-platform refusal preserves objects and accounting with zero SDK requests. Required build/security/CodeQL/dependency gates pass with the approved scoped H2 record. Qualified artifacts passed isolated graceful/cold-restart checks and local paired-host acceptance with native authentication, preserved records, automatic connector reconnection and 365-day retention. No live S3 migration or remote deployment is claimed.
+- Publish the JAR, POM and SHA256SUMS after [release run 41190650664](https://github.com/QRun-IO/qbit-printing/actions/runs/41190650664) passed all gates. Verify checksums and GitHub attestations for all three assets against the release tag and source; all packaged entry contents match the reviewed Query CI artifact.
 
 ## 0.1.3-rc.1 — 2026-10-30
 

CONTRIBUTING.md

@@ -9,3 +9,14 @@ Changes belong in a pull request with a concise behavior description and actual
 Keep the QBit compatible with QQQ 4.1+ and resolve runtime services through the current QQQ instance. Preserve tenant/device isolation and the distinction between local exposure (`available`) and server approval (`enabled`). Application callers must authorize destinations before submitting or emitting an effect.
 
 Maintainers create reviewed version tags. CI produces JAR/POM/checksum assets and publishes GitHub prereleases for hyphenated versions. Maven Central publication, deployment and physical printer tests are separate operations; this workflow does not perform them.
+
+## Script quality
+
+Owned `.github/scripts/*.py` follow the KofTwentyTwo standard at revision `fbfc8d2cf3b5e16ae9750b04cf9de1794f1e7152` (config adapted from its `python` profile): three-space indentation, Ruff 0.17.3 format/lint (locked in `uv.lock`) and strict Pyright 1.1.414 (Microsoft's npm package, a development-only dependency locked in `package-lock.json` and run through Node 24). Restore with `uv sync --locked` and `npm ci --ignore-scripts`, then run:
+
+```text
+uv run --locked --no-sync python .github/scripts/test-script-quality.py
+uv run --locked --no-sync python .github/scripts/check-script-quality.py
+```
+
+`check-script-quality.py` fails for any tracked Python outside `.github/scripts/` or any JavaScript/TypeScript (this repository has no tsconfig), and requires Pyright's analyzed-file count to equal the selected scripts. Pyright must run as `pyright -p .github`: it silently skips dot directories from a root config. Documented exceptions: CLI `print` only in `check-*.py`; synthetic test assertions and boundary constants; narrow inline `noqa` comments for fixed no-shell Git/interpreter calls and ordered fail-closed validators. Do not loosen a rule or add a type waiver to pass.

README.md

@@ -1,24 +1,33 @@
 # QQQ Printing
 
-Cloud printing for QQQ 4.1+, paired with the [Windows AppKit connector](https://github.com/QRun-IO/qqq-print-agent) and the [shared protocol](https://github.com/QRun-IO/qqq-print-protocol). The Windows connector initiates outbound HTTPS polling; the cloud needs no inbound route into the facility.
+Cloud printing for QQQ 4.1+, paired with the [Windows AppKit connector](https://github.com/QRun-IO/qqq-print-agent) and the [shared protocol](https://github.com/QRun-IO/qqq-print-protocol). The Windows connector opens an outbound, authenticated two-way WebSocket; documents download separately over HTTPS. The cloud needs no inbound route into the facility. Release candidate **0.3.0-rc.1** requires native printing API **2.0**, with no job/control polling fallback. Upgrade the server before the matching Windows connector.
 
-**Prerelease software**, tested against QQQ **4.1.0-RC.20** and Java 21. Audit source targets **0.1.4-rc.1**; the published baseline remains **0.1.3-rc.1** until the audit and release gates complete. The optional native UI demo uses QQQ frontend **1.0.0-RC.37**. GitHub releases provide a library JAR, POM and SHA-256 checksums. This repository does not claim Maven Central publication or provide a standalone executable/fat JAR.
+**Prerelease software**, tested against QQQ **4.1.0-RC.20** and Java 21. Current release candidate: [**0.3.0-rc.1**](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.3.0-rc.1). The previous [**0.2.0-rc.1**](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.2.0-rc.1) tagged build passed 110 tests and zero Checkstyle violations. The optional native UI demo uses QQQ frontend **1.0.0-RC.37**. GitHub releases provide a library JAR, POM and SHA-256 checksums, with build attestations for all three assets. Verify the exact downloaded release; publication does not establish installed or physical-output acceptance. This repository does not claim Maven Central publication or provide a standalone executable/fat JAR.
 
 Implemented: single-use enrollment, device credentials, inventory/approval, PDF/ZPL submission, durable JDBC queue, idempotency, claim/content/events, native QQQ setup/test-print processes, read-only device/printer/job tables and a durable enqueue effect target.
 
+The 0.2.0-rc.1 source adds native record/selection actions, per-device printers/jobs/queue/history, desired versus observed status and standard-session authentication at the discovered `/qqq/v1/qbit/printing` extension. Device credentials become secondary identity proof alongside the current QQQ user's permissions. Upgrade the server before the 0.2.0 Windows client, then explicitly associate an existing unbound pairing during sign-in. These changes are included in the published release above. See the [authentication contract](https://github.com/QRun-IO/qqq-print-protocol/blob/main/docs/QQQ-AUTHENTICATION.md); bound devices cannot fall back to legacy `/printing/v1` authentication.
+
 ```mermaid
 flowchart LR
   A[QQQ application / durable job] --> B[Printing QBit and JDBC queue]
-  C[Windows service] -->|Outbound HTTPS polling| B
+  C[Windows service] <-->|Client-initiated WSS: commands and status| B
+  C -->|Separate outbound HTTPS document streams| B
   C --> D[Windows spooler]
   D --> E[Local laser / Zebra]
 ```
 
-See the [screen walkthrough](docs/UI-WALKTHROUGH.md), [storage and retention](docs/STORAGE-AND-RETENTION.md), [operations and troubleshooting](docs/OPERATIONS.md), [contributing](CONTRIBUTING.md), [security reporting](SECURITY.md), [changelog](CHANGELOG.md), and [Apache-2.0 license](LICENSE).
+See the [real-time host integration](docs/REALTIME.md), [screen walkthrough](docs/UI-WALKTHROUGH.md), [storage and retention](docs/STORAGE-AND-RETENTION.md), [operations and troubleshooting](docs/OPERATIONS.md), [contributing](CONTRIBUTING.md), [security reporting](SECURITY.md), [changelog](CHANGELOG.md), and [Apache-2.0 license](LICENSE).
+
+## Local development
+
+Start an isolated native QQQ application, MinIO and optional Authentik with the
+[Docker development commands](dev/README.md). The default test runs synthetic
+Java/.NET WebSocket jobs and S3 checks without an installed connector or printer.
 
 ## Build and verify
 
-Install Java 21. Clone this repository and `qqq-print-protocol` as siblings. CI pins protocol commit `f4f977ca4aa6b749e6a52760eed5e53c99a7704d`; use that commit for reproducible compatibility tests. Use the checked-in wrapper (Maven 3.9.11).
+Install Java 21. Clone this repository and `qqq-print-protocol` as siblings. This source pins protocol commit `f3cbc02e9b0fb4fdfefaa59d976c04df747cc589`; use that commit for reproducible compatibility tests. Use the checked-in wrapper (Maven 3.9.11).
 
 ```powershell
 .\mvnw.cmd verify
@@ -29,7 +38,9 @@ On Linux/macOS use `bash ./mvnw verify` and the corresponding wrapper commands.
 
 Checkstyle runs during validate. Tests exercise real H2 persistence, native QQQ metadata/processes and real loopback HTTP through Javalin, including the shared fixtures and withdrawal of a locally exposed printer. Keep `../qqq-print-protocol` checked out or pass `-Dprinting.protocol.fixtures=<fixture-directory>`.
 
-## Local server
+## Legacy protocol demo
+
+The new Windows client needs the [authenticated local application](#authenticated-local-application) below, or a QQQ application hosting the native printing extension. This protocol-only demo is for explicitly enabled legacy diagnostics; it does not provide native user sign-in.
 
 Set `QQQ_PRINT_ADMIN_TOKEN` to a random value of at least 24 characters in the process environment; never put it in source or command arguments. Then:
 
@@ -43,7 +54,7 @@ For a directly managed Java process, classpath is `target/classes;` followed by
 
 ## Native QQQ UI preview
 
-A separate local demo serves the real QQQ frontend with synthetic device/printer/job records. It binds only to `127.0.0.1:18082`, uses mock authentication and registers no device transport routes, so its synthetic jobs cannot be claimed by a physical connector.
+A separate local demo serves the real QQQ frontend with synthetic device/printer/job records. It binds only to `127.0.0.1:18082` and uses mock authentication. Keep it isolated from real pairing data and physical connectors; it is a screen preview, not an authenticated deployment.
 
 ```powershell
 .\mvnw.cmd -Pui-demo package dependency:build-classpath '-Dmdep.outputFile=target/ui-classpath.txt' '-DincludeScope=runtime'
@@ -59,12 +70,14 @@ Open `http://127.0.0.1:18082`. On Linux/macOS use `:` as the classpath separator
 
 The protocol-only `PrintingDemo` and synthetic, mock-authenticated `PrintingUiDemo` remain separate. Do not point the synthetic demo at real paired printer data. The local host retains database document storage until an actual dedicated S3 binding is configured in a deployment-owned application; it does not claim a remote cloud deployment.
 
+Local native deployment is accepted with authentication and access-denial checks, preserved pairing/history, connector reconnection and 365-day retention. The previously accepted 0.1.4-rc.1 release passed 73 tests and zero Checkstyle violations; the user confirmed all three Query diagnostic outputs good. Production S3/IAM and remote deployment remain separate qualification work. The 0.2.0 controls/authentication release passed 25 real client/native QQQ interoperability checks; the user later confirmed installed Letter PDF and Zebra ZPL output, the Connected footer and both printers. These results do not qualify installed or physical behavior for 0.3.
+
 ## Add to a QQQ application
 
 For a source checkout, `mvnw.cmd install` (or `bash ./mvnw install`) installs the verified library into your local Maven repository. For a GitHub release, download the JAR, matching POM and `SHA256SUMS`, verify the checksums, then install those artifacts locally or through your organization's artifact repository. Example using the release files in the current directory:
 
 ```powershell
-.\mvnw.cmd install:install-file '-Dfile=qbit-printing-0.1.3-rc.1.jar' '-DpomFile=qbit-printing-0.1.3-rc.1.pom'
+.\mvnw.cmd install:install-file '-Dfile=qbit-printing-0.3.0-rc.1.jar' '-DpomFile=qbit-printing-0.3.0-rc.1.pom'
 ```
 
 After the artifact is available in your configured repository, add:
@@ -73,7 +86,7 @@ After the artifact is available in your configured repository, add:
 <dependency>
    <groupId>com.kingsrook.qbits</groupId>
    <artifactId>qbit-printing</artifactId>
-   <version>0.1.3-rc.1</version>
+   <version>0.3.0-rc.1</version>
 </dependency>
 ```
 
@@ -98,7 +111,7 @@ server.withAdditionalRouteProviders(List.of(new PrintingRoutes(printing, context
 
 `hostPrintingAdminGuard` is the host's own authenticated administrator policy, not a supplied library method. The service is bound to one tenant; use a separate host service instance for each tenant. Device token verification and job ownership are enforced on every device operation. Management service methods are intended for trusted application code; enforce user/facility authorization before calling them.
 
-The storage/scheduler options above are new in the pending 0.1.4 source. Configure a dedicated private printing bucket for the customer/environment through existing QQQ S3 metadata; no bucket credentials belong in printing forms. Admin retention defaults to 365 days after successful completion. Scheduled cleanup handles bounded batches every five minutes and preserves active, failed and uncertain work plus all receipts/history. Without a configured storage binding, legacy database documents remain supported; without a host scheduler, automatic cleanup does not run. Review [storage configuration, bucket isolation and S3 versioning](docs/STORAGE-AND-RETENTION.md) before deployment.
+The storage/scheduler options above are included in 0.1.4-rc.1. Configure a dedicated private printing bucket for the customer/environment through existing QQQ S3 metadata; no bucket credentials belong in printing forms. Admin retention defaults to 365 days after successful completion. Scheduled cleanup handles bounded batches every five minutes and preserves active, failed and uncertain work plus all receipts/history. Without a configured storage binding, legacy database documents remain supported; without a host scheduler, automatic cleanup does not run. Review [storage configuration, bucket isolation and S3 versioning](docs/STORAGE-AND-RETENTION.md) before deployment.
 
 Enrollment uses a named facility selector. Set `withFacilityPossibleValueSourceName("your_existing_facility_source")` to reuse an already registered host source and its record security. Without it, the standalone choice is **Default facility**. The backend validates the selection under the current user's permissions before issuing an enrollment code; typing or forging an unknown/foreign-tenant ID cannot bypass that check. Existing stored facility IDs are preserved; configure their original source to resolve their names.
 
@@ -114,7 +127,7 @@ Metadata names follow QBit conventions: tables and data sources use `printing_*`
 
 Two independent settings govern dispatch: `available` means the queue is present in the latest locally selected inventory; `enabled` means a QQQ administrator approved it. New submissions and claims require both. Removing a queue from local selection makes it unavailable without deleting its approval/history. An empty inventory withdraws all queues. Withdrawing a queue cannot retract a job already accepted by Windows.
 
-Application code calls `printing.submit(JSONObject)` with the shared `SubmitJobRequest` fields. A stable business idempotency key returns the same job when retried; changing document/options/target under the same key fails. PDF is sent as bytes encoded once in base64; ZPL is UTF-8 printer-ready bytes. Default limit is 20 MiB. Queue approval and format compatibility are checked before insertion.
+Application code calls `printing.submit(JSONObject)` with the shared `SubmitJobRequest` fields. A stable business idempotency key returns the same job when retried; changing document/options/target under the same key fails. PDF is sent as bytes encoded once in base64; ZPL is UTF-8 printer-ready bytes. Default decoded limits are 100 MiB for PDF and 20 MiB for ZPL, both configurable in the native Printing connection and limits process. Queue approval and format compatibility are checked before insertion.
 
 ```java
 JSONObject job = printing.submit(new JSONObject()
@@ -128,6 +141,8 @@ JSONObject job = printing.submit(new JSONObject()
 String printJobId = job.getString("jobId");
 ```
 
+For terminal and web clients the QBit also offers ready-made print processes: `PrintingRecordProcesses.registerAll(instance)` (after all host tables are added) puts **Print** on every readable table, rendering a record sheet from the table's sections and child lists; `printingPrintTableList` prints a grid of any table (columns, filter, sort, page or all rows, paper and orientation); `printingPrintText` prints text such as a screen capture. Opt a table out with `PrintingTableSettings().withPrintable(false)`. Each returns the queued job id in `printingJobIds`. `printingRenderToPdf` (extension 2.2.0) renders the same documents to a PDF download for the caller instead ("Save as PDF"), and every document carries the app header and footer the client sends (`headerApp`, `headerTitle`, `headerServer`, `headerUser`, `headerPrintedAt`, `footerLeft`, `footerNote`).
+
 The returned ID identifies durable queue acceptance. Check job status asynchronously. The [protocol v1 specification](https://github.com/QRun-IO/qqq-print-protocol/blob/f977bd01b62ceb7539190fd2861809537fcf504c/README.md) defines HTTP endpoints, JSON fields, integrity checks and lifecycle semantics.
 
 For durable QQQ jobs register `PrintEnqueueEffectTarget` as an `IDEMPOTENT_EXTERNAL` target in `DurableJobsMetaData`, then emit the submit-request payload. The target replaces the payload idempotency key with the durable effect key. Its SENT result means accepted into the queue, not physical output. This implementation uses its own JDBC transaction; do not register it as LOCAL_TX. Authorize the destination in the emitting process before writing the effect. QQQ's durable dispatcher runs with a `QSystemUserSession` and does not propagate the user's tenant keys. For that trusted outbox path only, the target resolves the service configured on the dispatcher's current QQQ instance; that service fixes the tenant and rejects devices belonging to another tenant. The payload cannot choose a service or tenant. A cached target resolves the current instance on every call. Inline user calls retain the `printing_tenant` scope check, and native management processes (including enrollment) still require both administrator permission and matching tenant scope. Do not expose direct effect emission through an arbitrary user-supplied target/payload endpoint.

dev/AUTHENTIK.md

@@ -0,0 +1,115 @@
+# Local Authentik reference
+
+Run the optional real-provider checks with Docker Compose and PowerShell 7.4+.
+The pinned fixture images use Linux/amd64; other hosts need Docker's corresponding
+Linux-container support or emulation:
+
+```powershell
+pwsh ./dev/Invoke-Dev.ps1 -Action Test -Authentik
+```
+
+The command creates a fresh, owned development project, runs the normal QQQ and
+MinIO smoke test plus the Authentik reference checks, then removes that project's
+containers and volumes. It does not operate the installed Windows connector,
+existing Docker stacks or physical printers. It needs no cloud account.
+
+For an environment that remains available for development, use `-Action Start`
+with an explicit `-StateDirectory` outside the checkout. Use that same directory
+with `-Action Test -Authentik`, then `-Action Stop` when finished. Stop destroys
+only that owned project's synthetic databases and objects; retained private
+reports are separate. See the [development command](Invoke-Dev.ps1) for port
+overrides. Authentik defaults to `http://127.0.0.1:19010`;
+its database port is not published. The QQQ host remains on standard TABLE
+authentication.
+
+## What the automated check establishes
+
+- Real Authentik 2026.8.5 starts with a separate PostgreSQL 16 Alpine database.
+- A synthetic confidential OAuth provider/application and development user are
+  configured through Authentik's API. The callback list is explicit and grants
+  are limited to authorization code and refresh. Access/refresh validity is
+  two/ten minutes for a future bounded renewal test.
+- Actual provider discovery has the expected issuer, same-origin endpoints and
+  S256 capability. A valid state/S256 request with the registered callback
+  continues to the provider login flow without following it. Changing only that
+  callback to an unregistered redirect is rejected before any user login.
+- The current QQQ RC.20 host advertises UI API 1.8 without `nativeSessionLogin`.
+  That expected absence is recorded as a native-client prerequisite failure,
+  not silently replaced by bearer authentication or an unpublished core.
+
+`auth-result.json` distinguishes those checks from browser login, renewal and
+the Windows callback, which are **not run**. Provider setup/discovery is not an
+OIDC user-session integration test. No password login dialog is automated.
+
+## Credentials and ownership
+
+The common entrypoint creates a protected state directory outside the checkout.
+`Invoke-Authentik.ps1 -Action Initialize` appends only its `AUTHENTIK_*` settings
+to `compose.env`, preserving the QQQ/MinIO settings. It records synthetic
+credentials in private `auth-secrets.json`; neither file belongs in Git, a bug
+report or terminal output. Bootstrap uses a Django password hash. The temporary
+bootstrap API token remains confined to this disposable project and disappears
+with its database at cleanup. Do not reuse these accounts outside the fixture.
+
+The Docker administrator can inspect container configuration. The scripts do not
+print credentials or provider error bodies, follow redirects with an API token,
+or request raw container logs. HTTP reads have a 15-second cancellation deadline
+and a 512 KiB response limit. Startup has a bounded readiness loop. Initializer
+replays retain credentials; conflicting or partial state is refused.
+
+Compose pins cached/public image digests, not floating tags:
+
+<!-- markdownlint-disable MD013 -->
+
+| Component | Image digest |
+| --- | --- |
+| Authentik server/worker 2026.8.5 | `ghcr.io/goauthentik/server@sha256:602227a86455d6772e3d16b7d852713c4f864f40df5df894abd1285bb53979a5` |
+| PostgreSQL 16 Alpine | `postgres@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea` |
+
+<!-- markdownlint-enable MD013 -->
+
+There is no Redis requirement for this Authentik version, Docker socket mount,
+outpost management, shared volume or automatic restart policy. Container and
+volume labels identify the exact generated Compose project. The common cleanup
+checks those labels before removing resources; it never performs a global prune.
+
+## Separate native-session qualification
+
+The Windows native path requires the centrally defined API 1.9 typed
+`AUTHORIZATION_CODE_PKCE_SESSION` grant and trusted HTTPS on both QQQ and provider
+origins. RC.20 does not supply that grant, and this HTTP development profile does
+not weaken the client's HTTPS rules. The synthetic reference callback is only a
+provider configuration value; no callback receiver or QQQ OAuth adapter is
+claimed here. The TABLE host and installed pairing are unchanged.
+
+The separate [experimental native profile](native-auth/README.md) builds an exact
+public, unreleased QQQ candidate inside Docker and uses private container-only
+HTTPS trust. On 2026-11-01 it passed actual provider login, native permission
+denials, logout replay rejection, renewal after expiry and provider revocation
+with the production Core client. Its synthetic HTTP driver and HTTPS callback
+receiver do not qualify the installed Windows browser UI or private URI callback.
+
+Production adoption still requires a compatible published central artifact
+tuple. Provider refresh tokens stay on the server. The short lifetime test does
+not prove months or years of unattended use. Do not route the private Windows
+callback to a live companion whose connection must remain intact.
+
+The setup follows the official [2026.8 Compose definition](https://goauthentik.io/version/2026.8/lifecycle/container/compose.yml),
+[bootstrap contract](https://docs.goauthentik.io/install-config/automated-install/)
+and [OAuth provider contract](https://docs.goauthentik.io/add-secure-apps/providers/oauth2/).
+The repository supplies the repeatable local setup; provider/browser acceptance
+is reported separately from TABLE authentication and printing workload tests.
+
+## Initializer regression tests
+
+With Pester 5 available, run `dev/tests/Authentik.Tests.ps1`. They use temporary
+files only: no Docker, HTTP, installed service or registry access is required.
+Disable Pester's unrelated registry fixture on Windows:
+
+```powershell
+$configuration = New-PesterConfiguration
+$configuration.Run.Path = './dev/tests/Authentik.Tests.ps1'
+$configuration.Run.Exit = $true
+$configuration.TestRegistry.Enabled = $false
+Invoke-Pester -Configuration $configuration
+```

dev/Dockerfile.client

@@ -0,0 +1,19 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b AS build
+# Exact reviewed published Core source; no workstation DLL or mutable branch.
+ADD --checksum=sha256:82fcdbf7240760939a63b219aeb15a2333b3a8a02b52307a8a328500fca71fb6 https://github.com/QRun-IO/qqq-print-agent/archive/346fc285198908c47a2ee9db7b9adb53d5e88c3c.tar.gz /tmp/client.tar.gz
+RUN mkdir /client && tar -xzf /tmp/client.tar.gz -C /client --strip-components=1 && rm /tmp/client.tar.gz
+RUN dotnet build /client/src/Qqq.PrintAgent.Core/Qqq.PrintAgent.Core.csproj -c Release -p:Platform=x64 -p:Version=0.3.1-rc.1 -p:RestoreLockedMode=true --nologo
+RUN mkdir /core && cp /client/src/Qqq.PrintAgent.Core/bin/x64/Release/net10.0/Qqq.PrintAgent.Core.dll /core/
+WORKDIR /fixture
+COPY dev/client .
+RUN dotnet build -c Release --nologo -o /out
+RUN dotnet /out/Workload.dll --check-discovery
+# SDK image is reused deliberately: one pinned image, no hidden host SDK dependency.
+FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b
+WORKDIR /app
+COPY --from=build /out .
+ENV DOTNET_EnableDiagnostics=0
+ENTRYPOINT ["dotnet","/app/Workload.dll"]

dev/Dockerfile.server

@@ -0,0 +1,26 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+FROM maven:3.9.11-eclipse-temurin-21@sha256:6fdc855a6ed81d288ca7ca37ac6ff5e9308b612485c0801d70b25a858c83d237 AS build
+WORKDIR /source
+COPY pom.xml mvnw ./
+COPY .mvn .mvn
+COPY checkstyle checkstyle
+COPY src src
+COPY LICENSE NOTICE ./
+RUN chmod +x mvnw && ./mvnw -B -Pui-demo -DskipTests package dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=target/runtime
+COPY dev/java /fixture-src
+RUN mkdir -p /fixture-classes && javac -proc:none -cp 'target/classes:target/runtime/*' -d /fixture-classes /fixture-src/*.java
+
+FROM eclipse-temurin:21-jdk-jammy@sha256:742daacb9316be4b6fc60258f6e4ac2a11882f6c597373c92290a57bfad0d2e0
+ARG SOURCE_COMMIT=unknown
+ENV PRINTING_SOURCE_COMMIT=$SOURCE_COMMIT
+WORKDIR /app
+COPY --from=build /source/target/classes classes
+COPY --from=build /source/target/runtime lib
+COPY --from=build /fixture-classes fixture
+COPY dev/log4j2.xml /app/log4j2.xml
+COPY dev/run-tests.sh /app/run-tests.sh
+RUN chmod 0555 /app/run-tests.sh
+ENTRYPOINT ["java","-Xmx768m","-Dlog4j.configurationFile=/app/log4j2.xml","-cp","/app/classes:/app/lib/*:/app/fixture"]
+CMD ["com.kingsrook.qbits.printing.DevHost"]

dev/Invoke-Authentik.ps1

@@ -0,0 +1,397 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+<#
+.SYNOPSIS
+Prepares or checks the optional, owned Authentik development fixture.
+.DESCRIPTION
+Initialize only writes private state. Test configures a fresh synthetic provider
+and checks its real HTTP discovery and rejection boundary; it never automates a
+user login or changes QQQ authentication. The common development entrypoint owns
+all Docker lifecycle operations. Provider response bodies and secrets are never
+printed, including on errors.
+#>
+[CmdletBinding()]
+param(
+   [Parameter(Mandatory)][ValidateSet('Initialize', 'Test')][string] $Action,
+   [Parameter(Mandatory)][string] $StateDirectory,
+   [Parameter(Mandatory)][ValidatePattern('^qbit-printing-dev-[a-z0-9-]{8,48}$')][string] $ProjectName,
+   [ValidateRange(1024, 65535)][int] $Port = 19010,
+   [ValidateRange(10, 300)][int] $ReadyTimeoutSeconds = 180
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+<# .SYNOPSIS Generates a private random value without placing it on a command line. #>
+function Get-FixtureSecret
+{
+   [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).TrimEnd('=').Replace('+', '-').Replace('/', '_')
+}
+
+<# .SYNOPSIS Limits the helper to an existing state directory outside the checkout. #>
+function Get-FixtureState
+{
+   param([string] $Directory)
+   $state = [IO.Path]::GetFullPath($Directory)
+   $repository = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..'))
+   $comparison = if($IsWindows) { [StringComparison]::OrdinalIgnoreCase } else { [StringComparison]::Ordinal }
+   if($state.Equals($repository, $comparison) -or $state.StartsWith($repository + [IO.Path]::DirectorySeparatorChar, $comparison))
+   {
+      throw 'Development secrets must be outside the source checkout.'
+   }
+   if(-not (Test-Path -LiteralPath $state -PathType Container) -or -not (Test-Path -LiteralPath (Join-Path $state 'compose.env') -PathType Leaf))
+   {
+      throw 'The common development entrypoint must create protected state and compose.env first.'
+   }
+   $ancestor = [IO.DirectoryInfo]::new($state)
+   while($null -ne $ancestor)
+   {
+      if(($ancestor.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)
+      {
+         throw 'Development state cannot use a symbolic link or reparse point.'
+      }
+      $ancestor = $ancestor.Parent
+   }
+   return $state
+}
+
+<# .SYNOPSIS Reads private configuration without echoing malformed JSON or credential values. #>
+function Get-FixtureConfiguration
+{
+   param([string] $Path)
+   try
+   {
+      $value = Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -AsHashtable
+      foreach($field in @('project', 'port', 'adminPassword', 'bootstrapToken', 'clientId', 'clientSecret', 'username', 'userPassword'))
+      {
+         if(-not $value.ContainsKey($field) -or $null -eq $value[$field]) { throw 'Missing field.' }
+      }
+      return $value
+   }
+   catch { throw 'The private Authentik configuration is unreadable or incomplete; its contents are withheld.' }
+}
+
+<# .SYNOPSIS Performs bounded same-origin HTTP without redirects or response-body diagnostics. #>
+function Invoke-FixtureHttp
+{
+   param(
+      [Parameter(Mandatory)][Net.Http.HttpClient] $Client,
+      [Parameter(Mandatory)][string] $Path,
+      [ValidateSet('GET', 'POST')][string] $Method = 'GET',
+      [object] $Body,
+      [string] $Token,
+      [int[]] $ExpectedStatus = @(200)
+   )
+   if(-not $Path.StartsWith('/', [StringComparison]::Ordinal) -or $Path.StartsWith('//', [StringComparison]::Ordinal))
+   {
+      throw 'Only an absolute path on the fixture origin is permitted.'
+   }
+   $request = [Net.Http.HttpRequestMessage]::new([Net.Http.HttpMethod]::new($Method), $Path)
+   $timeout = [Threading.CancellationTokenSource]::new([TimeSpan]::FromSeconds(15))
+   $response = $null
+   $status = 0
+   try
+   {
+      if($Token)
+      {
+         $request.Headers.Authorization = [Net.Http.Headers.AuthenticationHeaderValue]::new('Bearer', $Token)
+      }
+      if($null -ne $Body)
+      {
+         $request.Content = [Net.Http.StringContent]::new(($Body | ConvertTo-Json -Depth 12 -Compress), [Text.Encoding]::UTF8, 'application/json')
+      }
+      $response = $Client.SendAsync($request, [Net.Http.HttpCompletionOption]::ResponseHeadersRead, $timeout.Token).GetAwaiter().GetResult()
+      $status = [int]$response.StatusCode
+      if($status -notin $ExpectedStatus)
+      {
+         throw "Fixture HTTP status $status was not expected. Response content is withheld."
+      }
+      $stream = $response.Content.ReadAsStreamAsync($timeout.Token).GetAwaiter().GetResult()
+      $bytes = [IO.MemoryStream]::new()
+      try
+      {
+         $buffer = [byte[]]::new(8192)
+         while(($read = $stream.ReadAsync($buffer, 0, $buffer.Length, $timeout.Token).GetAwaiter().GetResult()) -gt 0)
+         {
+            if($bytes.Length + $read -gt 524288)
+            {
+               throw 'Fixture response exceeded the 512 KiB limit.'
+            }
+            $bytes.Write($buffer, 0, $read)
+         }
+         $text = [Text.Encoding]::UTF8.GetString($bytes.ToArray())
+         $data = if($text.Length -gt 0 -and $response.Content.Headers.ContentType.MediaType -eq 'application/json')
+         {
+            ConvertFrom-Json -InputObject $text -AsHashtable
+         }
+         else { $null }
+         return @{ Status = $status; Data = $data; Location = $response.Headers.Location }
+      }
+      finally
+      {
+         $bytes.Dispose()
+         $stream.Dispose()
+      }
+   }
+   catch
+   {
+      # The failing API may contain passwords/tokens in its error response.
+      $operation = [uri]::new($Client.BaseAddress, $Path).AbsolutePath
+      throw "Fixture $Method $operation failed (HTTP $status; 0 means no response). Response content and authentication values are withheld."
+   }
+   finally
+   {
+      if($null -ne $response) { $response.Dispose() }
+      $request.Dispose()
+      $timeout.Dispose()
+   }
+}
+
+<# .SYNOPSIS Requires one exact default object rather than choosing an arbitrary provider resource. #>
+function Get-FixtureObject
+{
+   param([Net.Http.HttpClient] $Client, [string] $Path, [string] $Token)
+   $page = (Invoke-FixtureHttp -Client $Client -Path $Path -Token $Token).Data
+   if($null -eq $page -or $page.results.Count -ne 1)
+   {
+      throw 'A required Authentik default object is missing or ambiguous.'
+   }
+   return $page.results[0]
+}
+
+$state = Get-FixtureState -Directory $StateDirectory
+$envPath = Join-Path $state 'compose.env'
+$secretPath = Join-Path $state 'auth-secrets.json'
+foreach($path in @($envPath, $secretPath))
+{
+   if((Test-Path -LiteralPath $path) -and ((Get-Item -LiteralPath $path -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)
+   {
+      throw 'Development configuration cannot use a symbolic link or reparse point.'
+   }
+}
+if($Action -eq 'Initialize')
+{
+   if(Test-Path -LiteralPath $secretPath)
+   {
+      $existing = Get-FixtureConfiguration -Path $secretPath
+      if($existing.project -ne $ProjectName -or $existing.port -ne $Port)
+      {
+         throw 'Existing Authentik state belongs to a different project or port.'
+      }
+      $existingEnvironment = Get-Content -LiteralPath $envPath -Raw
+      foreach($key in @('AUTHENTIK_HTTP_PORT', 'AUTHENTIK_POSTGRES_PASSWORD', 'AUTHENTIK_SECRET_KEY', 'AUTHENTIK_BOOTSTRAP_PASSWORD_HASH', 'AUTHENTIK_BOOTSTRAP_TOKEN'))
+      {
+         if([regex]::Matches($existingEnvironment, '(?m)^' + $key + '=').Count -ne 1)
+         {
+            throw 'The private Authentik environment is incomplete or ambiguous; use a fresh owned state directory.'
+         }
+      }
+      return
+   }
+   $contents = Get-Content -LiteralPath $envPath -Raw
+   if($contents -match '(?m)^AUTHENTIK_')
+   {
+      throw 'Partial Authentik initialization exists. Use a fresh owned state directory.'
+   }
+   $adminPassword = Get-FixtureSecret
+   $salt = Get-FixtureSecret
+   $passwordHash = [Convert]::ToBase64String([Security.Cryptography.Rfc2898DeriveBytes]::Pbkdf2($adminPassword, [Text.Encoding]::UTF8.GetBytes($salt), 1000000, [Security.Cryptography.HashAlgorithmName]::SHA256, 32))
+   $secrets = [ordered]@{
+      project = $ProjectName
+      port = $Port
+      adminPassword = $adminPassword
+      bootstrapToken = Get-FixtureSecret
+      clientId = $ProjectName
+      clientSecret = Get-FixtureSecret
+      username = 'printing-developer'
+      userPassword = Get-FixtureSecret
+   }
+   $secrets | ConvertTo-Json | Set-Content -LiteralPath $secretPath -Encoding utf8
+   $values = [ordered]@{
+      AUTHENTIK_HTTP_PORT = $Port
+      AUTHENTIK_POSTGRES_PASSWORD = Get-FixtureSecret
+      AUTHENTIK_SECRET_KEY = Get-FixtureSecret
+      AUTHENTIK_BOOTSTRAP_PASSWORD_HASH = 'pbkdf2_sha256$1000000$' + $salt + '$' + $passwordHash
+      AUTHENTIK_BOOTSTRAP_TOKEN = $secrets.bootstrapToken
+   }
+   # Single quotes preserve the dollar signs in Django's password hash.
+   $lines = @('') + @($values.GetEnumerator() | ForEach-Object { $_.Key + "='" + $_.Value + "'" })
+   Add-Content -LiteralPath $envPath -Value $lines -Encoding utf8
+   if(-not $IsWindows)
+   {
+      [IO.File]::SetUnixFileMode($secretPath, [IO.UnixFileMode]::UserRead -bor [IO.UnixFileMode]::UserWrite)
+   }
+   return
+}
+
+$secrets = Get-FixtureConfiguration -Path $secretPath
+if($secrets.project -cne $ProjectName -or $secrets.port -ne $Port -or $secrets.clientId -cne $ProjectName -or $secrets.username -cne 'printing-developer')
+{
+   throw 'Authentik state does not match the owned development project.'
+}
+$handler = [Net.Http.HttpClientHandler]::new()
+$handler.AllowAutoRedirect = $false
+$handler.UseProxy = $false
+$handler.UseCookies = $false
+$client = [Net.Http.HttpClient]::new($handler)
+$client.BaseAddress = [uri]"http://127.0.0.1:$Port"
+$client.Timeout = [Threading.Timeout]::InfiniteTimeSpan
+try
+{
+   $deadline = [DateTimeOffset]::UtcNow.AddSeconds($ReadyTimeoutSeconds)
+   $ready = $false
+   do
+   {
+      try
+      {
+         $authorization = Get-FixtureObject -Client $client -Path '/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent' -Token $secrets.bootstrapToken
+         $invalidation = Get-FixtureObject -Client $client -Path '/api/v3/flows/instances/?slug=default-provider-invalidation-flow' -Token $secrets.bootstrapToken
+         $ready = $true
+      }
+      catch
+      {
+         if([DateTimeOffset]::UtcNow -ge $deadline) { throw 'Authentik did not become ready before the bounded startup deadline.' }
+         Start-Sleep -Seconds 1
+      }
+   } while(-not $ready)
+
+   $mappingIds = @(foreach($scope in @('openid', 'profile', 'email', 'offline_access'))
+   {
+      (Get-FixtureObject -Client $client -Path "/api/v3/propertymappings/provider/scope/?scope_name=$scope" -Token $secrets.bootstrapToken).pk
+   })
+   $providerPage = (Invoke-FixtureHttp -Client $client -Path ('/api/v3/providers/oauth2/?client_id=' + $secrets.clientId) -Token $secrets.bootstrapToken).Data
+   $callback = "http://127.0.0.1:$Port/reference-callback/"
+   if($providerPage.results.Count -eq 0)
+   {
+      $provider = (Invoke-FixtureHttp -Client $client -Method POST -Path '/api/v3/providers/oauth2/' -Token $secrets.bootstrapToken -ExpectedStatus @(201) -Body @{
+         name = $ProjectName
+         authorization_flow = $authorization.pk
+         invalidation_flow = $invalidation.pk
+         client_type = 'confidential'
+         grant_types = @('authorization_code', 'refresh_token')
+         client_id = $secrets.clientId
+         client_secret = $secrets.clientSecret
+         access_code_validity = 'minutes=1'
+         access_token_validity = 'minutes=2'
+         refresh_token_validity = 'minutes=10'
+         redirect_uris = @(@{ matching_mode = 'strict'; url = $callback })
+         property_mappings = $mappingIds
+         issuer_mode = 'per_provider'
+      }).Data
+   }
+   elseif($providerPage.results.Count -eq 1)
+   {
+      $provider = $providerPage.results[0]
+      if($provider.name -ne $ProjectName) { throw 'The fixture provider identity changed.' }
+   }
+   else { throw 'The fixture provider identity is ambiguous.' }
+   if($provider.redirect_uris.Count -ne 1 -or $provider.redirect_uris[0].matching_mode -cne 'strict' -or
+      $provider.redirect_uris[0].url -cne $callback -or $provider.client_type -cne 'confidential' -or
+      $provider.access_token_validity -cne 'minutes=2' -or $provider.refresh_token_validity -cne 'minutes=10' -or
+      (@($provider.grant_types | Sort-Object) -join ',') -cne 'authorization_code,refresh_token' -or
+      @($mappingIds | Where-Object { $_ -notin $provider.property_mappings }).Count -ne 0)
+   {
+      throw 'The existing provider configuration differs from the bounded reference settings.'
+   }
+
+   $applicationPage = (Invoke-FixtureHttp -Client $client -Path ('/api/v3/core/applications/?slug=' + $ProjectName) -Token $secrets.bootstrapToken).Data
+   if($applicationPage.results.Count -eq 0)
+   {
+      $null = Invoke-FixtureHttp -Client $client -Method POST -Path '/api/v3/core/applications/' -Token $secrets.bootstrapToken -ExpectedStatus @(201) -Body @{ name = $ProjectName; slug = $ProjectName; provider = $provider.pk; policy_engine_mode = 'all' }
+   }
+   elseif($applicationPage.results.Count -ne 1 -or $applicationPage.results[0].provider -ne $provider.pk)
+   {
+      throw 'The fixture application does not match its provider.'
+   }
+   $userPage = (Invoke-FixtureHttp -Client $client -Path ('/api/v3/core/users/?username=' + $secrets.username) -Token $secrets.bootstrapToken).Data
+   if($userPage.results.Count -eq 0)
+   {
+      $user = (Invoke-FixtureHttp -Client $client -Method POST -Path '/api/v3/core/users/' -Token $secrets.bootstrapToken -ExpectedStatus @(201) -Body @{ username = $secrets.username; name = 'Printing development user'; email = 'printing-developer@example.invalid'; is_active = $true; type = 'internal' }).Data
+   }
+   elseif($userPage.results.Count -eq 1)
+   {
+      $user = $userPage.results[0]
+      if($user.name -cne 'Printing development user') { throw 'The synthetic user identity changed.' }
+   }
+   else { throw 'The synthetic user identity is ambiguous.' }
+   # Reusing the same generated value also recovers an interrupted first setup.
+   $null = Invoke-FixtureHttp -Client $client -Method POST -Path ("/api/v3/core/users/$($user.pk)/set_password/") -Token $secrets.bootstrapToken -ExpectedStatus @(204) -Body @{ password = $secrets.userPassword }
+
+   $issuer = "http://127.0.0.1:$Port/application/o/$ProjectName/"
+   $discovery = (Invoke-FixtureHttp -Client $client -Path "/application/o/$ProjectName/.well-known/openid-configuration").Data
+   if($discovery.issuer -cne $issuer -or 'S256' -notin $discovery.code_challenge_methods_supported)
+   {
+      throw 'The real provider discovery does not match the fixture issuer and S256 capability.'
+   }
+   foreach($endpoint in @('authorization_endpoint', 'token_endpoint', 'userinfo_endpoint', 'jwks_uri'))
+   {
+      $uri = [uri]$discovery[$endpoint]
+      if($uri.GetLeftPart([UriPartial]::Authority) -cne "http://127.0.0.1:$Port")
+      {
+         throw 'Provider discovery returned an endpoint outside the fixture origin.'
+      }
+   }
+   $verifier = Get-FixtureSecret
+   $challenge = [Convert]::ToBase64String([Security.Cryptography.SHA256]::HashData([Text.Encoding]::ASCII.GetBytes($verifier))).TrimEnd('=').Replace('+', '-').Replace('/', '_')
+   $stateValue = Get-FixtureSecret
+   $authorize = "/application/o/authorize/?client_id=$($secrets.clientId)&response_type=code&scope=openid%20profile%20email%20offline_access&state=$stateValue&code_challenge=$challenge&code_challenge_method=S256&prompt=login&redirect_uri="
+   $accepted = Invoke-FixtureHttp -Client $client -Path ($authorize + [uri]::EscapeDataString($callback)) -ExpectedStatus @(302, 303)
+   if($null -eq $accepted.Location)
+   {
+      throw 'The registered redirect did not continue to the real provider login flow.'
+   }
+   $login = [uri]::new($client.BaseAddress, $accepted.Location)
+   if($login.GetLeftPart([UriPartial]::Authority) -cne "http://127.0.0.1:$Port" -or -not $login.AbsolutePath.StartsWith('/if/flow/', [StringComparison]::Ordinal))
+   {
+      throw 'The registered redirect did not continue to the same-origin provider login flow.'
+   }
+   # Change only the callback: a generic malformed authorization request is not proof.
+   $invalidRedirect = [uri]::EscapeDataString("http://127.0.0.1:$Port/not-registered/")
+   $null = Invoke-FixtureHttp -Client $client -Path ($authorize + $invalidRedirect) -ExpectedStatus @(400)
+   $qqqPortMatch = [regex]::Match((Get-Content -LiteralPath $envPath -Raw), '(?m)^QQQ_HTTP_PORT=[''"]?(\d+)[''"]?\s*$')
+   if(-not $qqqPortMatch.Success) { throw 'The common environment has no QQQ HTTP port.' }
+   $qqqHandler = [Net.Http.HttpClientHandler]::new()
+   $qqqHandler.AllowAutoRedirect = $false
+   $qqqHandler.UseProxy = $false
+   $qqqClient = [Net.Http.HttpClient]::new($qqqHandler)
+   try
+   {
+      $qqqClient.BaseAddress = [uri]("http://127.0.0.1:" + $qqqPortMatch.Groups[1].Value)
+      $qqqClient.Timeout = [Threading.Timeout]::InfiniteTimeSpan
+      $qqqClient.DefaultRequestHeaders.Add('X-QQQ-Client', 'api/printing-dev-reference')
+      $version = (Invoke-FixtureHttp -Client $qqqClient -Path '/qqq/v1/version').Data
+   }
+   finally { $qqqClient.Dispose() }
+   if($version.apiVersion -ne '1.8.0' -or 'nativeSessionLogin' -in $version.features)
+   {
+      throw 'The core capability baseline changed; review the Authentik qualification scope before proceeding.'
+   }
+   [ordered]@{
+      status = 'PASS'
+      observedUtc = [DateTimeOffset]::UtcNow.ToString('O')
+      project = $ProjectName
+      providerOrigin = "http://127.0.0.1:$Port"
+      providerVersion = '2026.8.5'
+      discovery = 'PASS'
+      registeredRedirect = 'LOGIN_REQUIRED'
+      unregisteredRedirect = 'REJECTED'
+      qqqApiVersion = $version.apiVersion
+      nativeSessionLogin = 'UNAVAILABLE_EXPECTED'
+      browserLogin = 'NOT_RUN_OPERATOR_REQUIRED'
+      renewal = 'NOT_RUN'
+      windowsCallback = 'NOT_RUN_REQUIRES_QUALIFIED_CORE_AND_HTTPS'
+   } | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $state 'auth-result.json') -Encoding utf8
+   Write-Output 'Authentik reference discovery and redirect rejection passed; QQQ native browser login remains unavailable on RC.20.'
+}
+catch
+{
+   @{ status = 'FAILED'; observedUtc = [DateTimeOffset]::UtcNow.ToString('O'); project = $ProjectName; message = 'Reference checks failed; no browser or native-login success is claimed.' } |
+      ConvertTo-Json | Set-Content -LiteralPath (Join-Path $state 'auth-result.json') -Encoding utf8
+   throw
+}
+finally
+{
+   $client.Dispose()
+}

dev/Invoke-Dev.ps1

@@ -0,0 +1,502 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+<#
+.SYNOPSIS
+Starts, tests, or removes one owned local Docker printing environment.
+.DESCRIPTION
+Uses synthetic accounts and documents. Never imports installed device credentials,
+contacts printers, changes host trust, or prunes shared Docker resources.
+#>
+[CmdletBinding()]
+param(
+   [ValidateSet('Start', 'Test', 'Stop')][string]$Action = 'Test',
+   [string]$StateDirectory,
+   [switch]$Authentik,
+   [switch]$ExperimentalNativeAuth,
+   [ValidateSet(40, 10000)][int]$Workload = 40,
+   [ValidateRange(1024, 65535)][int]$QqqPort = 19081,
+   [ValidateRange(1024, 65535)][int]$MinioPort = 19095,
+   [ValidateRange(1024, 65535)][int]$AuthentikPort = 19010
+)
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+$sourceRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..'))
+$ephemeral = $Action -eq 'Test' -and [string]::IsNullOrWhiteSpace($StateDirectory)
+if ($ExperimentalNativeAuth)
+{
+   if ($Action -ne 'Test')
+   {
+      throw 'Experimental native authentication is a disposable Test-only profile.'
+   }
+   $Authentik = $true
+}
+
+function Assert-StateLocation([string]$Path)
+{
+   <# .SYNOPSIS Rejects links before any private state is read or written. #>
+   $ancestor = [IO.DirectoryInfo]::new($Path)
+   while ($null -ne $ancestor)
+   {
+      if (![string]::IsNullOrEmpty($ancestor.LinkTarget) -or ($ancestor.Exists -and ($ancestor.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0))
+      {
+         throw 'Development state cannot use a symbolic link or reparse point.'
+      }
+      $ancestor = $ancestor.Parent
+   }
+   foreach ($name in @('owner.json', 'compose.env', 'compose.yaml', 'compose.authentik.yaml', 'compose.native-auth.yaml', 'auth-secrets.json', 'qqq-result.json', 'auth-result.json', 'native-input.json', 'native-auth-result.json', 'native-auth-server-errors.json'))
+   {
+      $file = [IO.FileInfo]::new((Join-Path $Path $name))
+      if (![string]::IsNullOrEmpty($file.LinkTarget) -or ($file.Exists -and ($file.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0))
+      {
+         throw 'Development state files cannot use symbolic links or reparse points.'
+      }
+   }
+}
+function Get-RecordedAuthentikPort
+{
+   <# .SYNOPSIS Restores the existing environment port without reading it from caller defaults. #>
+   $lines = @(Get-Content -LiteralPath $script:envFile | Where-Object { $_.StartsWith('AUTHENTIK_HTTP_PORT=', [StringComparison]::Ordinal) })
+   if ($lines.Count -ne 1 -or $lines[0] -cnotmatch '^AUTHENTIK_HTTP_PORT=([0-9]{4,5})$')
+   {
+      throw 'Recorded Authentik port is missing or invalid.'
+   }
+   $port = [int]$Matches[1]
+   if ($port -lt 1024 -or $port -gt 65535)
+   {
+      throw 'Recorded Authentik port is outside the supported range.'
+   }
+   return $port
+}
+function Get-FixtureSecret
+{
+   <# .SYNOPSIS Generates only disposable local credentials. #>
+   return [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
+}
+function Protect-State([string]$Path)
+{
+   <# .SYNOPSIS Restricts the generated state to its user and local administrators. #>
+   if ($IsWindows)
+   {
+      $acl = [Security.AccessControl.DirectorySecurity]::new()
+      $acl.SetAccessRuleProtection($true, $false)
+      foreach ($sid in @([Security.Principal.WindowsIdentity]::GetCurrent().User,
+            [Security.Principal.SecurityIdentifier]::new('S-1-5-18'), [Security.Principal.SecurityIdentifier]::new('S-1-5-32-544')))
+      {
+         $acl.AddAccessRule([Security.AccessControl.FileSystemAccessRule]::new($sid, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow'))
+      }
+      Set-Acl -LiteralPath $Path -AclObject $acl
+   }
+   else
+   {
+      [IO.File]::SetUnixFileMode($Path, [IO.UnixFileMode]::UserRead -bor [IO.UnixFileMode]::UserWrite -bor [IO.UnixFileMode]::UserExecute)
+   }
+}
+function Set-FixtureEnvironment
+{
+   [CmdletBinding(SupportsShouldProcess)]
+   param([string]$Name, [string]$Value)
+   <# .SYNOPSIS Updates one safe dotenv field without displaying secret values. #>
+   if ($Name -cnotmatch '^[A-Z_]+$' -or $Value -match '[\r\n]')
+   {
+      throw 'Unsafe generated environment field.'
+   }
+   if (!$PSCmdlet.ShouldProcess($Name, 'Write protected fixture setting'))
+   {
+      return
+   }
+   $lines = @()
+   if (Test-Path -LiteralPath $script:envFile)
+   {
+      $lines = @(Get-Content -LiteralPath $script:envFile | Where-Object { !$_.StartsWith($Name + '=', [StringComparison]::Ordinal) })
+   }
+   [IO.File]::WriteAllLines($script:envFile, @($lines) + @($Name + '=' + $Value))
+}
+function Invoke-Compose([string[]]$Arguments)
+{
+   <# .SYNOPSIS Runs only this recorded Compose project. #>
+   & docker compose @script:composeArguments @Arguments
+   if ($LASTEXITCODE -ne 0)
+   {
+      throw 'Owned Docker Compose operation failed; inspect local command output.'
+   }
+}
+function Assert-OwnedResource
+{
+   <# .SYNOPSIS Refuses cleanup if any project resource lacks the ownership label. #>
+   $ids = @(& docker ps -aq --filter "label=com.docker.compose.project=$script:project")
+   if ($LASTEXITCODE -ne 0)
+   {
+      throw 'Cannot inspect owned Docker containers.'
+   }
+   foreach ($id in $ids)
+   {
+      $label = & docker inspect $id --format '{{index .Config.Labels "io.qrun.printing.dev"}}'
+      if ($LASTEXITCODE -ne 0 -or $label -cne $script:project)
+      {
+         throw 'Container ownership mismatch; cleanup refused.'
+      }
+   }
+   $networks = @(& docker network ls -q --filter "label=com.docker.compose.project=$script:project")
+   if ($LASTEXITCODE -ne 0)
+   {
+      throw 'Cannot inspect owned Docker networks.'
+   }
+   foreach ($network in $networks)
+   {
+      $label = & docker network inspect $network --format '{{index .Labels "io.qrun.printing.dev"}}'
+      if ($LASTEXITCODE -ne 0 -or $label -cne $script:project)
+      {
+         throw 'Network ownership mismatch; cleanup refused.'
+      }
+   }
+   $volumes = @(& docker volume ls -q --filter "label=com.docker.compose.project=$script:project")
+   if ($LASTEXITCODE -ne 0)
+   {
+      throw 'Cannot inspect owned Docker volumes.'
+   }
+   foreach ($volume in $volumes)
+   {
+      $label = & docker volume inspect $volume --format '{{index .Labels "io.qrun.printing.dev"}}'
+      if ($LASTEXITCODE -ne 0 -or $label -cne $script:project)
+      {
+         throw 'Volume ownership mismatch; cleanup refused.'
+      }
+   }
+}
+function Stop-OwnedEnvironment
+{
+   [CmdletBinding(SupportsShouldProcess)]
+   param()
+   <# .SYNOPSIS Removes only this environment's containers, network and synthetic volumes. #>
+   if (!$PSCmdlet.ShouldProcess($script:project, 'Remove this owned development environment and its synthetic data'))
+   {
+      return
+   }
+   Assert-OwnedResource
+   Invoke-Compose @('--profile', 'test', '--profile', 'auth', '--profile', 'native-auth', 'down', '--remove-orphans', '--volumes', '--timeout', '30')
+}
+function ConvertTo-ProviderErrorSummary([string[]]$Lines)
+{
+   <# .SYNOPSIS Retains only exception types and bounded source-frame coordinates. #>
+   $types = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
+   $frames = [Collections.Generic.List[object]]::new()
+   $warnings = @{invalidClientIdentifier = $false; nonApplicableAuthenticationFlow = $false; failedToResolveApplication = $false}
+   foreach ($line in ($Lines | Select-Object -Last 1000))
+   {
+      if ($line.Length -gt 65536) { continue }
+      $warnings.invalidClientIdentifier = $warnings.invalidClientIdentifier -or $line.Contains('Invalid client identifier', [StringComparison]::Ordinal)
+      $warnings.nonApplicableAuthenticationFlow = $warnings.nonApplicableAuthenticationFlow -or $line.Contains('Non-applicable authentication flow', [StringComparison]::Ordinal)
+      $warnings.failedToResolveApplication = $warnings.failedToResolveApplication -or $line.Contains('failed to resolve application', [StringComparison]::Ordinal)
+      try { $record = ConvertFrom-Json -InputObject $line -AsHashtable -ErrorAction Stop }
+      catch { continue }
+      if ($record -isnot [Collections.IDictionary]) { continue }
+      foreach ($exception in @($record['exception']))
+      {
+         if ($exception -isnot [Collections.IDictionary]) { continue }
+         $type = [string]$exception['exc_type']
+         if ($types.Count -lt 16 -and ($type -cmatch '^[A-Za-z_][A-Za-z0-9_.]{0,119}(Error|Exception)$' -or $type -cin @('PermissionDenied', 'NotAuthenticated', 'AuthenticationFailed', 'Throttled'))) { [void]$types.Add($type) }
+         foreach ($frame in @($exception['frames']))
+         {
+            if ($frames.Count -ge 12 -or $frame -isnot [Collections.IDictionary]) { continue }
+            $filename = [string]$frame['filename']
+            $function = [string]$frame['name']
+            $lineNumber = 0
+            if ($filename.Length -le 300 -and $filename -cmatch '^/authentik/[A-Za-z0-9_./-]+\.py$' -and
+               $function -cmatch '^[A-Za-z0-9_<>.]{1,120}$' -and
+               [int]::TryParse([string]$frame['lineno'], [ref]$lineNumber) -and $lineNumber -gt 0)
+            {
+               $frames.Add(@{filename = $filename; line = $lineNumber; function = $function})
+            }
+         }
+      }
+   }
+   return @{exceptionTypes = @($types | Sort-Object); frames = @($frames.ToArray()); warnings = $warnings}
+}
+function Save-ProviderErrorSummary
+{
+   <# .SYNOPSIS Reads bounded logs only from the exact owned synthetic provider. #>
+   $ids = @(& docker ps -aq --filter "label=com.docker.compose.project=$script:project" --filter 'label=com.docker.compose.service=authentik-server')
+   if ($LASTEXITCODE -ne 0 -or $ids.Count -ne 1 -or $ids[0] -cnotmatch '^[a-f0-9]{12,64}$') { return }
+   $label = & docker inspect $ids[0] --format '{{index .Config.Labels "io.qrun.printing.dev"}}'
+   if ($LASTEXITCODE -ne 0 -or $label -cne $script:project) { throw 'Provider diagnostic ownership mismatch.' }
+   $lines = @(& docker logs --tail 1000 $ids[0] 2>&1 | ForEach-Object { $_.ToString() })
+   if ($LASTEXITCODE -ne 0) { return }
+   $summary = ConvertTo-ProviderErrorSummary $lines
+   $lines = $null
+   Assert-StateLocation $StateDirectory
+   $summary | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $StateDirectory 'native-auth-server-errors.json')
+}
+function Wait-OwnedContainer([string]$Id, [int]$Seconds)
+{
+   <# .SYNOPSIS Observes bounded completion without accessing application data. #>
+   $deadline = [DateTime]::UtcNow.AddSeconds($Seconds)
+   do
+   {
+      $state = & docker inspect $Id --format '{{.State.Running}}|{{.State.ExitCode}}'
+      if ($LASTEXITCODE -ne 0)
+      {
+         throw 'Owned fixture container disappeared.'
+      }
+      if ($state.StartsWith('false|', [StringComparison]::Ordinal))
+      {
+         return [int]$state.Split('|')[1]
+      }
+      Start-Sleep -Seconds 1
+   } while ([DateTime]::UtcNow -lt $deadline)
+   throw 'Bounded fixture deadline expired; owned resources will be cleaned.'
+}
+function Assert-WorkloadClientSucceeded([string]$Id, [int]$ExitCode, [string]$Run, [string]$Reports)
+{
+   <# .SYNOPSIS Preserves private client evidence and reports only fixed failure classifications. #>
+   if ($ExitCode -eq 0) { return }
+   $stage = 'unknown'
+   $failureType = 'UnknownFailure'
+   try
+   {
+      $path = Join-Path $Reports 'result.json'
+      & docker cp "${Id}:/work/$Run/result.json" $path 2>&1 | Out-Null
+      if ($LASTEXITCODE -eq 0 -and (Test-Path -LiteralPath $path -PathType Leaf) -and (Get-Item -LiteralPath $path).Length -le 65536)
+      {
+         $result = Get-Content -LiteralPath $path -Raw | ConvertFrom-Json -AsHashtable
+         if ($result -is [Collections.IDictionary] -and $result['success'] -ceq $false)
+         {
+            if ($result['stage'] -is [string] -and $result['stage'] -cin @('input', 'native_login_and_channels', 'workload', 'logout'))
+            {
+               $stage = $result['stage']
+            }
+            if ($result['error'] -is [string] -and $result['error'] -cin @('QqqSessionException', 'HttpRequestException', 'IOException', 'InvalidDataException', 'JsonException', 'OperationCanceledException', 'TaskCanceledException', 'UnauthorizedAccessException', 'WebSocketException', 'TimeoutException', 'InvalidOperationException'))
+            {
+               $failureType = $result['error']
+            }
+         }
+      }
+   }
+   catch
+   {
+      # Missing or malformed diagnostics must not hide the failed client or expose raw exception text.
+      $stage = 'unknown'
+      $failureType = 'UnknownFailure'
+   }
+   throw "Workload client failed at $stage ($failureType); see protected results."
+}
+
+if ([string]::IsNullOrWhiteSpace($StateDirectory))
+{
+   if ($Action -eq 'Stop')
+   {
+      throw 'Stop requires the state directory printed by Start.'
+   }
+   $base = if ($IsWindows)
+   {
+      Join-Path $env:LOCALAPPDATA 'QQQ/PrintingDevelopment'
+   }
+   else
+   {
+      Join-Path $HOME '.local/state/qqq-printing-development'
+   }
+   $StateDirectory = Join-Path $base ('environment-' + [Guid]::NewGuid().ToString('N'))
+}
+$StateDirectory = [IO.Path]::GetFullPath($StateDirectory)
+if ($StateDirectory.StartsWith($sourceRoot + [IO.Path]::DirectorySeparatorChar, [StringComparison]::OrdinalIgnoreCase))
+{
+   throw 'Keep secret state outside the repository.'
+}
+Assert-StateLocation $StateDirectory
+$ownerFile = Join-Path $StateDirectory 'owner.json'
+$script:envFile = Join-Path $StateDirectory 'compose.env'
+$createdState = $false
+if (Test-Path -LiteralPath $StateDirectory)
+{
+   if (!(Test-Path -LiteralPath $ownerFile))
+   {
+      throw 'Existing state directory lacks this tool ownership record.'
+   }
+   $owner = Get-Content -LiteralPath $ownerFile -Raw | ConvertFrom-Json
+   if ($owner.sourceRoot -cne $sourceRoot -or $owner.project -cnotmatch '^qbit-printing-dev-[a-f0-9]{32}$')
+   {
+      throw 'State ownership mismatch.'
+   }
+   $script:project = $owner.project
+   $Authentik = [bool]$owner.authentik
+   $savedNativeProfile = $null -ne $owner.PSObject.Properties['experimentalNativeAuth'] -and [bool]$owner.experimentalNativeAuth
+   if ($ExperimentalNativeAuth -and !$savedNativeProfile)
+   {
+      throw 'An existing standard environment cannot be repurposed for experimental native authentication.'
+   }
+   $ExperimentalNativeAuth = $savedNativeProfile
+   if ($ExperimentalNativeAuth -and $Action -eq 'Start')
+   {
+      throw 'Experimental native authentication is a disposable Test-only profile.'
+   }
+}
+else
+{
+   if ($Action -eq 'Stop')
+   {
+      throw 'Owned state directory does not exist.'
+   }
+   [IO.Directory]::CreateDirectory($StateDirectory) | Out-Null
+   Protect-State $StateDirectory
+   $createdState = $true
+   $script:project = 'qbit-printing-dev-' + [Guid]::NewGuid().ToString('N')
+   $commit = (& git -C $sourceRoot rev-parse HEAD).Trim()
+   if ($LASTEXITCODE -ne 0 -or $commit -cnotmatch '^[a-f0-9]{40}$')
+   {
+      throw 'Cannot record source identity.'
+   }
+   foreach ($field in @{PRINTING_DEV_PROJECT = $project; DEV_SOURCE_DIR = $sourceRoot.Replace('\', '/'); SOURCE_COMMIT = $commit; QQQ_HTTP_PORT = "$QqqPort"; MINIO_HTTP_PORT = "$MinioPort"; MINIO_ROOT_USER = 'printing-development'; MINIO_ROOT_PASSWORD = (Get-FixtureSecret); QQQ_DATABASE_PASSWORD = (Get-FixtureSecret); QQQ_ADMIN_PASSWORD = (Get-FixtureSecret); QQQ_MANAGEMENT_TOKEN = (Get-FixtureSecret) }.GetEnumerator())
+   {
+      Set-FixtureEnvironment $field.Key $field.Value
+   }
+   Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'compose.yaml') -Destination (Join-Path $StateDirectory 'compose.yaml')
+   if ($Authentik)
+   {
+      & (Join-Path $PSScriptRoot 'Invoke-Authentik.ps1') -Action Initialize -StateDirectory $StateDirectory -ProjectName $project -Port $AuthentikPort
+      Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'compose.authentik.yaml') -Destination (Join-Path $StateDirectory 'compose.authentik.yaml')
+   }
+   if ($ExperimentalNativeAuth)
+   {
+      & (Join-Path $PSScriptRoot 'Invoke-NativeAuth.ps1') -Action Initialize -StateDirectory $StateDirectory -ProjectName $project
+      Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'compose.native-auth.yaml') -Destination (Join-Path $StateDirectory 'compose.native-auth.yaml')
+   }
+   @{project = $project; sourceRoot = $sourceRoot; sourceCommit = $commit; authentik = [bool]$Authentik; experimentalNativeAuth = [bool]$ExperimentalNativeAuth; createdAt = [DateTime]::UtcNow.ToString('O') } | ConvertTo-Json | Set-Content -LiteralPath $ownerFile
+}
+$script:composeArguments = @('--project-name', $project, '--env-file', $envFile, '-f', (Join-Path $StateDirectory 'compose.yaml'))
+if ($Authentik)
+{
+   $script:composeArguments += @('-f', (Join-Path $StateDirectory 'compose.authentik.yaml'))
+}
+if ($ExperimentalNativeAuth)
+{
+   $script:composeArguments += @('-f', (Join-Path $StateDirectory 'compose.native-auth.yaml'))
+}
+if ($Action -eq 'Stop')
+{
+   Stop-OwnedEnvironment
+   Write-Output "Stopped owned development environment. Reports remain in $StateDirectory"
+   return
+}
+
+if ($ExperimentalNativeAuth)
+{
+   $nativePassed = $false
+   try
+   {
+      Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'build', 'native-qqq', 'native-client')
+      Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'up', '-d', 'authentik-server', 'authentik-worker', 'native-tls')
+      Invoke-Compose @('exec', '-T', 'native-tls', '/bin/sh', '/etc/caddy/copy-root.sh')
+      Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'up', '-d', 'native-qqq')
+      Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'run', '--rm', '--use-aliases', 'native-client')
+      & (Join-Path $PSScriptRoot 'Invoke-NativeAuth.ps1') -Action VerifyResult -StateDirectory $StateDirectory -ProjectName $project
+      $nativePassed = $true
+   }
+   finally
+   {
+      try
+      {
+         if (!$nativePassed) { Save-ProviderErrorSummary }
+      }
+      finally { Stop-OwnedEnvironment }
+      Write-Output "Protected experimental native-auth result: $(Join-Path $StateDirectory 'native-auth-result.json')"
+   }
+   return
+}
+
+if ($Action -eq 'Start')
+{
+   $services = @('minio', 'qqq')
+   $profiles = @()
+   if ($Authentik)
+   {
+      $profiles = @('--profile', 'auth'); $services += @('authentik-server', 'authentik-worker')
+   }
+   try
+   {
+      Invoke-Compose ($profiles + @('up', '-d', '--build') + $services); & (Join-Path $PSScriptRoot 'Test-DevelopmentHost.ps1') -StateDirectory $StateDirectory
+   }
+   catch
+   {
+      if ($createdState)
+      {
+         Stop-OwnedEnvironment
+      }; throw
+   }
+   Write-Output "Owned environment: $StateDirectory"
+   Write-Output 'Read QQQ_ADMIN_PASSWORD in its protected compose.env; username is developer. No password is logged.'
+   return
+}
+
+$testRun = 'run-' + [Guid]::NewGuid().ToString('N')
+Set-FixtureEnvironment 'TEST_RUN' $testRun
+Set-FixtureEnvironment 'WORKLOAD_MODE' $(if ($Workload -eq 10000)
+   {
+      'burst'
+   }
+   else
+   {
+      'idle'
+   })
+$reports = Join-Path $StateDirectory $testRun
+[IO.Directory]::CreateDirectory($reports) | Out-Null
+$passed = $false
+try
+{
+   if ($Authentik)
+   {
+      Invoke-Compose @('--profile', 'auth', 'up', '-d', '--build', 'qqq', 'authentik-server', 'authentik-worker')
+      & (Join-Path $PSScriptRoot 'Test-DevelopmentHost.ps1') -StateDirectory $StateDirectory
+      & (Join-Path $PSScriptRoot 'Invoke-Authentik.ps1') -Action Test -StateDirectory $StateDirectory -ProjectName $project -Port (Get-RecordedAuthentikPort)
+   }
+   Invoke-Compose @('--profile', 'test', 'up', '-d', '--build', 'test-client')
+   $client = (& docker compose @composeArguments ps -a -q test-client).Trim()
+   $server = (& docker compose @composeArguments ps -a -q test-server).Trim()
+   if ($client -cnotmatch '^[a-f0-9]{64}$' -or $server -cnotmatch '^[a-f0-9]{64}$')
+   {
+      throw 'Owned fixture identity missing.'
+   }
+   $clientExit = Wait-OwnedContainer $client 1200
+   Assert-WorkloadClientSucceeded -Id $client -ExitCode $clientExit -Run $testRun -Reports $reports
+   $serverExit = Wait-OwnedContainer $server 45
+   foreach ($file in @('result.json', 'server-result.json', 'stopped.json', 's3/results.json', 's3/completed-checks.json'))
+   {
+      $destination = Join-Path $reports $file.Replace('/', '-')
+      & docker cp "${server}:/work/$testRun/$file" $destination
+      if ($LASTEXITCODE -ne 0)
+      {
+         throw 'Required sanitized fixture result missing.'
+      }
+   }
+   if ($clientExit -ne 0 -or $serverExit -ne 0)
+   {
+      throw 'Fixture failed; see protected results.'
+   }
+   $clientResult = Get-Content (Join-Path $reports 'result.json') -Raw | ConvertFrom-Json
+   $serverResult = Get-Content (Join-Path $reports 'server-result.json') -Raw | ConvertFrom-Json
+   $s3Result = Get-Content (Join-Path $reports 's3-results.json') -Raw | ConvertFrom-Json
+   if (!$clientResult.success -or !$serverResult.success -or !$s3Result.passed -or $clientResult.jobs -ne $Workload -or @($s3Result.checks).Count -ne 65)
+   {
+      throw 'Result invariants failed.'
+   }
+   $passed = $true
+}
+finally
+{
+   & docker compose @composeArguments logs --no-color --no-log-prefix test-server test-client 2>&1 | Set-Content -LiteralPath (Join-Path $reports 'fixture.log')
+   if ($ephemeral)
+   {
+      Stop-OwnedEnvironment
+   }
+   else
+   {
+      Assert-OwnedResource
+      Invoke-Compose @('--profile', 'test', 'rm', '--stop', '--force', 'test-client', 'test-server', 'minio-test')
+   }
+   @{passed = $passed; workload = $Workload; physicalPrinting = $false; tlsQualified = $false; finishedAt = [DateTime]::UtcNow.ToString('O') } | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $reports 'execution.json')
+   Write-Output "Protected developer-test results: $reports"
+}
+if (!$passed)
+{
+   throw 'Development qualification did not pass.'
+}

dev/Invoke-NativeAuth.ps1

@@ -0,0 +1,110 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+<#
+.SYNOPSIS
+Prepares or verifies the opt-in, unpublished native-session Docker qualification.
+.DESCRIPTION
+Docker lifecycle belongs to Invoke-Dev.ps1. This helper creates only protected
+synthetic input and reads a bounded sanitized report. It never installs trust,
+uses host Maven caches, starts a browser, or operates the installed connector.
+#>
+[CmdletBinding()]
+param(
+   [Parameter(Mandatory)][ValidateSet('Initialize', 'VerifyResult')][string] $Action,
+   [Parameter(Mandatory)][string] $StateDirectory,
+   [Parameter(Mandatory)][ValidatePattern('^qbit-printing-dev-[a-z0-9-]{8,48}$')][string] $ProjectName
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+$coreSource = 'ecf0f550a0357cec6387c2b54efca128a405a629'
+$clientSource = '346fc285198908c47a2ee9db7b9adb53d5e88c3c'
+$state = [IO.Path]::GetFullPath($StateDirectory)
+$repository = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..'))
+$comparison = if($IsWindows) { [StringComparison]::OrdinalIgnoreCase } else { [StringComparison]::Ordinal }
+if($state.Equals($repository, $comparison) -or $state.StartsWith($repository + [IO.Path]::DirectorySeparatorChar, $comparison))
+{
+   throw 'Experimental credentials must be outside the checkout.'
+}
+$envFile = Join-Path $state 'compose.env'
+$inputFile = Join-Path $state 'native-input.json'
+$resultFile = Join-Path $state 'native-auth-result.json'
+if(-not (Test-Path -LiteralPath $envFile -PathType Leaf))
+{
+   throw 'The common entrypoint must initialize protected owned state first.'
+}
+
+if($Action -eq 'VerifyResult')
+{
+   if(-not (Test-Path -LiteralPath $resultFile -PathType Leaf) -or (Get-Item -LiteralPath $resultFile).Length -gt 65536)
+   {
+      throw 'The experimental result is missing or exceeds its bounded size.'
+   }
+   try { $report = Get-Content -LiteralPath $resultFile -Raw | ConvertFrom-Json -AsHashtable }
+   catch { throw 'The experimental result is malformed; its contents are withheld.' }
+   $required = @('untrusted-tls-refused', 'typed-native-grant', 'real-provider-login', 'wrong-origin-cookie-denied', 'permission-denied-user', 'logout-replay-denied', 'server-refresh-after-expiry', 'provider-revocation-denied')
+   if($report.status -cne 'PASS' -or $report.scope -cne 'DEVELOPMENT_ONLY_UNRELEASED' -or
+      $report.coreSource -cne $coreSource -or $report.clientSource -cne $clientSource -or
+      $report.project -cne $ProjectName -or @($required | Where-Object { $_ -notin $report.checks }).Count -ne 0)
+   {
+      throw 'The experimental native-session qualification did not pass its exact source and required checks.'
+   }
+   Write-Output 'Experimental native-session provider checks passed; the candidate is unpublished and no installed/browser-UI acceptance is claimed.'
+   return
+}
+
+if((Test-Path -LiteralPath $inputFile) -or (Get-Content -LiteralPath $envFile -Raw) -match '(?m)^NATIVE_')
+{
+   throw 'Experimental native tests require a fresh owned environment; partial state is not reused.'
+}
+try
+{
+   $auth = Get-Content -LiteralPath (Join-Path $state 'auth-secrets.json') -Raw | ConvertFrom-Json -AsHashtable
+   if($auth.project -cne $ProjectName -or $auth.clientId -cne $ProjectName) { throw 'Wrong owner.' }
+}
+catch { throw 'Private Authentik bootstrap state is absent or does not match this project.' }
+$random = [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
+$deniedPassword = [Convert]::ToBase64String($random).TrimEnd('=').Replace('+', '-').Replace('/', '_')
+$issuer = "https://auth.printing.internal/application/o/$ProjectName/"
+$inputData = [ordered]@{
+   project = $ProjectName
+   coreSource = $coreSource
+   clientSource = $clientSource
+   providerOrigin = 'https://auth.printing.internal'
+   qqqOrigin = 'https://qqq.printing.internal'
+   issuer = $issuer
+   callback = 'https://callback.printing.internal/oauth/callback'
+   adminToken = $auth.bootstrapToken
+   clientId = $auth.clientId
+   clientSecret = $auth.clientSecret
+   authorizedUsername = 'printing-authorized'
+   authorizedPassword = $auth.userPassword
+   deniedUsername = 'printing-denied'
+   deniedPassword = $deniedPassword
+}
+$inputData | ConvertTo-Json | Set-Content -LiteralPath $inputFile -Encoding utf8
+@{ status = 'NOT_RUN'; scope = 'DEVELOPMENT_ONLY_UNRELEASED'; project = $ProjectName } |
+   ConvertTo-Json | Set-Content -LiteralPath $resultFile -Encoding utf8
+$values = [ordered]@{
+   NATIVE_QQQ_DATABASE_PASSWORD = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
+   NATIVE_QQQ_REFRESH_KEY = [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
+   NATIVE_AUTH_ISSUER = $issuer
+   NATIVE_AUTH_CLIENT_ID = $auth.clientId
+   NATIVE_AUTH_CLIENT_SECRET = $auth.clientSecret
+   NATIVE_AUTH_INPUT_FILE = $inputFile.Replace('\', '/')
+   NATIVE_AUTH_RESULT_FILE = $resultFile.Replace('\', '/')
+}
+foreach($entry in $values.GetEnumerator())
+{
+   if($entry.Value -match '[\r\n'']') { throw 'Unsupported experimental environment value.' }
+}
+Add-Content -LiteralPath $envFile -Value @($values.GetEnumerator() | ForEach-Object { $_.Key + "='" + $_.Value + "'" }) -Encoding utf8
+if(-not $IsWindows)
+{
+   foreach($file in @($inputFile, $resultFile))
+   {
+      [IO.File]::SetUnixFileMode($file, [IO.UnixFileMode]::UserRead -bor [IO.UnixFileMode]::UserWrite)
+   }
+}

dev/README.md

@@ -0,0 +1,133 @@
+# Local Docker development
+
+Use this repository to start a separate QQQ application or run synthetic printing
+checks. Nothing imports an installed connector's pairing, accesses physical
+printers, or needs a cloud account. Docker Compose and PowerShell 7.4+ are required;
+Git identifies the checkout. Docker must support Linux/amd64 containers. The first
+build downloads pinned public images, Maven dependencies and the verified Windows
+Core source archive. Java and .NET run inside Docker; neither host SDK is required.
+
+## Start, test and stop
+
+From the repository root, the default command runs 65 S3 checks and 40 network
+jobs, saves protected reports, and removes its containers and synthetic volumes:
+
+```powershell
+pwsh ./dev/Invoke-Dev.ps1 -Action Test
+```
+
+For a persistent development application, start it and keep the state-directory
+path printed by the command:
+
+```powershell
+pwsh ./dev/Invoke-Dev.ps1 -Action Start
+pwsh ./dev/Invoke-Dev.ps1 -Action Test -StateDirectory '<printed state directory>'
+pwsh ./dev/Invoke-Dev.ps1 -Action Stop -StateDirectory '<printed state directory>'
+```
+
+Open `http://127.0.0.1:19081`. The standard QQQ TABLE login username is `developer`.
+Read `QQQ_ADMIN_PASSWORD` from the generated, protected `compose.env` locally;
+never paste that file into an issue or commit it. There is no default password.
+The host provides native printing screens, settings, a dedicated MinIO document
+bucket and scheduled retention. No printer is enrolled automatically in this host.
+The test workload uses a separate disposable database and object store.
+
+Add `-Authentik` when creating an environment or running a fresh test to include
+real Authentik/PostgreSQL. See [the provider checks and remaining native grant
+prerequisite](AUTHENTIK.md). Provider discovery does not establish successful OIDC
+user login or refresh; the current QQQ RC.20 API lacks that native-client grant.
+
+```powershell
+pwsh ./dev/Invoke-Dev.ps1 -Action Test -Authentik
+pwsh ./dev/Invoke-Dev.ps1 -Action Test -Workload 10000
+```
+
+The optional 10,000-job run keeps admission limits enabled, uses eight synthetic
+clients across two tenants, and reports client process memory, latency and
+receipt counts. It is a bounded burst, not a day-long soak or physical throughput
+claim. The default 40-job run measures idle event delivery one job at a time.
+
+## Isolation and cleanup
+
+Each environment has a unique `qbit-printing-dev-<random>` Compose project and
+matching ownership labels. All published ports bind only to `127.0.0.1`: QQQ19081,
+MinIO19095 and optional Authentik19010. Override them with `-QqqPort`, `-MinioPort`
+and `-AuthentikPort` when creating a new environment. Occupied ports fail startup;
+the command never stops another service to free them. PostgreSQL is not published.
+
+State defaults to the current user's application-data directory, outside the
+checkout, with private filesystem permissions. A custom `-StateDirectory` must
+also be outside the checkout. It holds generated fixture credentials, frozen
+Compose files, ownership records and sanitized result files. Docker administrators
+can inspect container configuration; use these credentials only for this fixture.
+
+`Stop` validates container, network and volume ownership before removing that
+project's resources. **It deletes that environment's synthetic databases and
+objects.** It leaves reports and ordinary image/build caches in place and never
+runs a global prune. A fresh one-command `Test` performs this cleanup in `finally`,
+including on failure. Tests against an existing environment remove only their
+three test containers; finish with `Stop` to remove its disposable test volume and
+the persistent development environment. Do not edit its frozen ownership files.
+
+Images are pinned by digest in Compose/Dockerfiles. Containers have bounded CPU
+and memory, no automatic restart, and no Docker socket. The default profile has
+no host credential or source mounts. QQQ/test containers additionally cap process
+counts. Builds copy
+only explicit source inputs. The QQQ and MinIO containers share their own network
+namespace so the existing loopback S3 backend can be used without relaxing
+production endpoint validation.
+
+## What the results mean
+
+- The S3 fixture exercises the actual QQQ `StorageAction`/S3 backend and AWS SDK,
+  including a multipart-size document, hashes, tenant namespaces, immutable
+  binding checks, retention and unrelated-object preservation.
+- The workload uses the real current Java server and pinned Windows Core client:
+  native TABLE authentication, outbound WebSocket notifications, event-driven
+  claims, document downloads and durable server receipts. A fake file printer
+  verifies bytes and rejects duplicate submission. It cannot produce paper.
+- The fixture's client receipt journal is intentionally simple; these results do
+  not replace production SQLite crash-recovery tests. MinIO fixture credentials
+  are unrestricted within their owned store and do not qualify production IAM.
+- Connections here are HTTP/WebSocket on an isolated local project. TLS, provider
+  browser consent/renewal, real deployment policies and hardware behavior are
+  separate qualifications. No silent bearer-authentication fallback is added.
+
+Results include `result.json`, `server-result.json`, `s3-results.json` and
+`execution.json` under a run directory. The persistent host also writes
+`qqq-result.json`; optional provider checks write `auth-result.json`. Treat raw
+fixture logs as private even though only synthetic accounts/documents are used.
+
+The client Dockerfile pins commit `346fc285198908c47a2ee9db7b9adb53d5e88c3c`
+and verifies its source archive SHA-256 before compilation. The Java image builds
+this checkout, including local edits, and records its Git HEAD for context; a Git
+HEAD alone does not certify a dirty tree as that released artifact. This tooling
+is outside the production JAR and adds no application runtime dependency.
+
+## Script regressions
+
+With Pester 5 installed, the initializer and cleanup-ownership tests need no Docker
+or network. Disable Pester's unrelated registry fixture on Windows:
+
+```powershell
+$configuration = New-PesterConfiguration
+$configuration.Run.Path = './dev/tests'
+$configuration.Run.Exit = $true
+$configuration.TestRegistry.Enabled = $false
+Invoke-Pester -Configuration $configuration
+```
+
+## Experimental native sign-in
+
+The separate [native sign-in profile](native-auth/README.md) builds an explicitly
+selected upstream candidate and uses container-private TLS trust. It mounts only
+public Caddy configuration and specific protected fixture input/result files.
+It is opt-in, Test-only, and does not change the default released QQQ dependency.
+
+## Continuous integration
+
+The development workflow runs the Pester and PowerShell analysis checks on
+Windows and Ubuntu for every pull request and main-branch push. Ubuntu also runs
+the real 40-job/S3 Docker smoke. The longer experimental native-auth profile is
+an explicit manual workflow option; it is not silently substituted for the
+released dependency baseline.

dev/Test-DevelopmentHost.ps1

@@ -0,0 +1,140 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+<# .SYNOPSIS Checks the owned local QQQ development host without enrolling or printing. #>
+[CmdletBinding()]
+param([Parameter(Mandatory)][string]$StateDirectory)
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+$state = [IO.Path]::GetFullPath($StateDirectory)
+$owner = Get-Content -LiteralPath (Join-Path $state 'owner.json') -Raw | ConvertFrom-Json
+if ($owner.project -cnotmatch '^qbit-printing-dev-[a-f0-9]{32}$')
+{
+   throw 'Expected an owned development environment.'
+}
+$values = @{}
+foreach ($line in Get-Content -LiteralPath (Join-Path $state 'compose.env'))
+{
+   if ($line -match '^([A-Z_]+)=(.*)$')
+   {
+      $values[$Matches[1]] = $Matches[2]
+   }
+}
+$port = [int]$values.QQQ_HTTP_PORT
+if ($port -lt 1024 -or $port -gt 65535 -or $port -in @(18081, 18086))
+{
+   throw 'Expected a separate development port.'
+}
+$origin = "http://127.0.0.1:$port"
+$handler = [Net.Http.HttpClientHandler]::new()
+$handler.UseProxy = $false
+$handler.AllowAutoRedirect = $false
+$handler.CookieContainer = [Net.CookieContainer]::new()
+$client = [Net.Http.HttpClient]::new($handler)
+$client.BaseAddress = [Uri]$origin
+$client.Timeout = [TimeSpan]::FromSeconds(15)
+$client.MaxResponseContentBufferSize = 1048576
+$client.DefaultRequestHeaders.Add('X-QQQ-Client', 'api/printing-development-check')
+$client.DefaultRequestHeaders.Add('Origin', $origin)
+$loggedIn = $false
+
+function Invoke-DevelopmentRequest([string]$Path, [string]$Method = 'GET', [string]$Authorization)
+{
+   <# .SYNOPSIS Sends one bounded native request, without returning credentials. #>
+   $request = [Net.Http.HttpRequestMessage]::new([Net.Http.HttpMethod]::new($Method), $Path)
+   if ($Method -eq 'POST')
+   {
+      $request.Content = [Net.Http.StringContent]::new('{}', [Text.Encoding]::UTF8, 'application/json')
+   }
+   if ($Authorization)
+   {
+      $request.Headers.TryAddWithoutValidation('Authorization', $Authorization) | Out-Null
+   }
+   $response = $null
+   try
+   {
+      $response = $client.SendAsync($request).GetAwaiter().GetResult()
+      if (!$response.IsSuccessStatusCode)
+      {
+         throw 'Owned native endpoint returned an unsuccessful status.'
+      }
+      return $response.Content.ReadAsStringAsync().GetAwaiter().GetResult()
+   }
+   finally
+   {
+      if ($null -ne $response)
+      {
+         $response.Dispose()
+      }; $request.Dispose()
+   }
+}
+try
+{
+   $deadline = [DateTime]::UtcNow.AddSeconds(90)
+   do
+   {
+      try
+      {
+         $version = (Invoke-DevelopmentRequest '/qqq/v1/version') | ConvertFrom-Json; break
+      }
+      catch [Net.Http.HttpRequestException]
+      {
+         if ([DateTime]::UtcNow -ge $deadline)
+         {
+            throw
+         }; Start-Sleep -Seconds 1
+      }
+   } while ($true)
+   if (@($version.extensions | Where-Object { $_.name -ceq 'printing' -and $_.version -ceq '2.0.0' }).Count -ne 1)
+   {
+      throw 'Expected current printing extension.'
+   }
+   $metadata = (Invoke-DevelopmentRequest '/qqq/v1/metaData/authentication') | ConvertFrom-Json
+   if ($metadata.type -cne 'TABLE_BASED')
+   {
+      throw 'Development host must retain standard TABLE authentication.'
+   }
+   $basic = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('developer:' + $values.QQQ_ADMIN_PASSWORD))
+   try
+   {
+      $null = Invoke-DevelopmentRequest -Path '/qqq/v1/manageSession' -Method POST -Authorization $basic
+   }
+   finally
+   {
+      $basic = $null; $values = $null
+   }
+   $cookies = $handler.CookieContainer.GetCookies([Uri]$origin)
+   $cookie = $cookies['sessionId']; if ($null -eq $cookie)
+   {
+      $cookie = $cookies['sessionUUID']
+   }
+   $loggedIn = $null -ne $cookie
+   if (!$loggedIn -or !$cookie.HttpOnly)
+   {
+      throw 'Native HttpOnly session was not established.'
+   }
+   $identity = (Invoke-DevelopmentRequest '/qqq/v1/qbit/printing/session') | ConvertFrom-Json
+   if ($identity.principalId -cne 'developer' -or $identity.tenantId -cne 'development')
+   {
+      throw 'Native development identity mismatch.'
+   }
+   $html = Invoke-DevelopmentRequest '/'
+   if (!$html.Contains('<html', [StringComparison]::OrdinalIgnoreCase))
+   {
+      throw 'Native frontend asset missing.'
+   }
+   $null = Invoke-DevelopmentRequest -Path '/qqq/v1/logout' -Method POST
+   $loggedIn = $false
+   @{passed = $true; nativeTableLogin = $true; principalAndTenantVerified = $true; frontendHtml = $true; logout = $true; workSubmitted = $false; observedUtc = [DateTime]::UtcNow.ToString('O') } |
+      ConvertTo-Json | Set-Content -LiteralPath (Join-Path $state 'qqq-result.json')
+   Write-Output 'Owned QQQ native login, identity, frontend asset and logout passed; no work submitted.'
+}
+finally
+{
+   if ($loggedIn)
+   {
+      $null = Invoke-DevelopmentRequest -Path '/qqq/v1/logout' -Method POST
+   }
+   $client.Dispose()
+}

dev/client/DiscoveryChecks.cs

@@ -0,0 +1,60 @@
+// Copyright 2026 Kingsrook, LLC
+
+// SPDX-License-Identifier: Apache-2.0
+using System.Net;
+using System.Text.Json;
+using Qqq.PrintAgent.Core.Authentication;
+
+internal static class DiscoveryChecks
+{
+   internal static async Task RunAsync()
+   {
+      (string Version, bool Accepted)[] cases =
+      [
+         ("2.0.0", true), ("2.1.0", true), ("2.9.17", true),
+         ("1.9.0", false), ("3.0.0", false), ("2.1", false),
+         ("2.01.0", false), ("2.1.0-rc.1", false), ("not-a-version", false)
+      ];
+      foreach((string version, bool expected) in cases)
+      {
+         using var handler = new DiscoveryHandler(version);
+         using var client = new QqqSessionClient(new Uri("https://printing.example.invalid"), handler);
+         bool accepted = false;
+         try
+         {
+            await WorkloadDiscovery.DiscoverRealtimeAsync(client, CancellationToken.None);
+            accepted = true;
+         }
+         catch(QqqSessionException error) when(error.Failure == QqqSessionException.FailureKind.ConfigurationRequired) { }
+         catch(InvalidDataException) { }
+         if(accepted != expected || handler.Requests != 1)
+         {
+            throw new InvalidDataException($"Discovery compatibility case {version} failed.");
+         }
+      }
+      Console.WriteLine($"Discovery compatibility checks passed: {cases.Length}.");
+   }
+
+   private sealed class DiscoveryHandler(string version) : HttpMessageHandler
+   {
+      internal int Requests { get; private set; }
+
+      protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+      {
+         if(request.Method != HttpMethod.Get || request.RequestUri?.AbsolutePath != "/qqq/v1/version"
+            || request.Headers.Contains("Cookie") || request.Headers.Contains("Authorization"))
+         {
+            throw new InvalidOperationException("Discovery must precede authentication.");
+         }
+         Requests++;
+         string json = JsonSerializer.Serialize(new
+         {
+            apiVersion = "1.8.0",
+            features = new[] { "version", "metaData", "processes", "processCancel", "extensions", "widgets" },
+            clientChannels = new[] { "api" },
+            extensions = new[] { new { name = "printing", version, pathPrefix = "/qbit/printing" } }
+         });
+         return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(json) });
+      }
+   }
+}

dev/client/Program.cs

@@ -0,0 +1,149 @@
+// Copyright 2026 Kingsrook, LLC
+
+// SPDX-License-Identifier: Apache-2.0
+using System.Collections.Concurrent;
+using System.Diagnostics;
+using System.Globalization;
+using System.Net.WebSockets;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Channels;
+using Qqq.PrintAgent.Core.Authentication;
+using Qqq.PrintAgent.Core.Printing;
+internal static class Program {
+ static int Completed; static readonly byte[] Expected=Encoding.ASCII.GetBytes("^XA^FO20,20^FDSYNTHETIC NOT PRINTED^FS"+new string(' ',980)+"^XZ");
+ static async Task<int> Main(string[] args) {
+  if(args is ["--check-discovery"]) { await DiscoveryChecks.RunAsync(); return 0; }
+  string folder=Path.GetFullPath(args[0]); string stage="input";
+  using var timeout=new CancellationTokenSource(TimeSpan.FromMinutes(18));
+  List<Lane> lanes=[]; long peak=0; var timer=Stopwatch.StartNew();
+  try {
+   using JsonDocument input=JsonDocument.Parse(await File.ReadAllTextAsync(Path.Combine(folder,"input.json")));
+   stage="native_login_and_channels";
+   bool idle=input.RootElement.GetProperty("idle").GetBoolean(); int perLane=input.RootElement.GetProperty("jobsPerLane").GetInt32(); int total=perLane*8; int index=0;
+   foreach(var value in input.RootElement.GetProperty("lanes").EnumerateArray()) {
+    Uri origin=new(value.GetProperty("origin").GetString()!);
+    Require(origin.IsLoopback && origin.Port is not (18081 or 18086),"disposable origin");
+    var client=new QqqSessionClient(origin,allowLoopbackHttp:true);
+    await WorkloadDiscovery.DiscoverRealtimeAsync(client,timeout.Token);
+    await client.GetAuthenticationMetadataAsync(timeout.Token);
+    await client.SignInWithPasswordAsync(value.GetProperty("username").GetString()!,value.GetProperty("password").GetString()!,timeout.Token);
+    await client.BindDeviceAsync(new(value.GetProperty("deviceId").GetString()!,value.GetProperty("deviceToken").GetString()!),cancellationToken:timeout.Token);
+    var binding=await client.GetSessionIdentityAsync(timeout.Token);
+    Require(binding.TenantId==value.GetProperty("tenant").GetString(),"authoritative tenant");
+    var connection=await Connection.Open(client,timeout.Token);
+    lanes.Add(new(client,connection,Path.Combine(folder,"lane-"+index++),perLane,folder));
+   }
+   Require(lanes.Count==8,"eight lanes");
+   // Authoritative native proof check: tenant A cannot bind a real tenant B device.
+   var foreign=input.RootElement.GetProperty("lanes")[4]; bool denied=false;
+   using(var outsider=new QqqSessionClient(new Uri(input.RootElement.GetProperty("lanes")[0].GetProperty("origin").GetString()!),allowLoopbackHttp:true)) {
+    await outsider.DiscoverAsync(timeout.Token);await outsider.GetAuthenticationMetadataAsync(timeout.Token);
+    await outsider.SignInWithPasswordAsync("operator",input.RootElement.GetProperty("lanes")[0].GetProperty("password").GetString()!,timeout.Token);
+    try {await outsider.BindDeviceAsync(new(foreign.GetProperty("deviceId").GetString()!,foreign.GetProperty("deviceToken").GetString()!),cancellationToken:timeout.Token);}catch(QqqSessionException){denied=true;}
+    Require(denied,"cross tenant proof refused");await outsider.SignOutAsync(timeout.Token);
+   }
+   stage="workload";
+   var tasks=lanes.Select(lane=>lane.Run(timeout.Token)).ToArray();
+   await File.WriteAllTextAsync(Path.Combine(folder,"ready"),"ready",timeout.Token);
+   Task all=Task.WhenAll(tasks);
+   while(!all.IsCompleted) {
+    peak=Math.Max(peak,Process.GetCurrentProcess().WorkingSet64);
+    await Task.WhenAny(all,Task.Delay(1000,timeout.Token));timeout.Token.ThrowIfCancellationRequested();
+   }
+   await all;
+   Require(lanes.Sum(l=>l.Printer.Count)==total,"exact fake submission count");
+   Require(lanes.All(l=>l.Journal.Pending().Count==0),"no unacknowledged receipts");
+   stage="logout";foreach(var lane in lanes)await lane.Client.SignOutAsync(timeout.Token);
+   double[] latencies=lanes.SelectMany(l=>l.Latencies).Order().ToArray();
+   await File.WriteAllTextAsync(Path.Combine(folder,"result.json"),JsonSerializer.Serialize(new {
+    success=true,jobs=total,idle,tenants=2,devices=8,elapsedSeconds=timer.Elapsed.TotalSeconds,jobsPerSecond=total/timer.Elapsed.TotalSeconds,
+    peakClientWorkingSetBytes=peak,p50EnqueueToAckMillis=latencies[total/2],p95EnqueueToAckMillis=latencies[(int)(total*0.95)],p99EnqueueToAckMillis=latencies[(int)(total*0.99)],
+    realCoreWorker=true,fakePrinterBackend=true,fixtureJournal=true,serverReceiptsDurable=true,crossTenantProofRefused=denied,
+    submissionReplays=idle?0:400,receiptReplays=idle?0:400,notificationToClaimMillis=lanes.SelectMany(l=>l.ClaimLatency).ToArray(),notificationToDownloadCompletedMillis=lanes.SelectMany(l=>l.DownloadLatency).ToArray(),periodicJobPolling=false,transport="HTTP/WS loopback; no TLS qualification",realPrinterCalls=0,
+    runtime=Environment.Version.ToString(),coreVersion=typeof(PrintWorker).Assembly.GetName().Version?.ToString()
+   },new JsonSerializerOptions{WriteIndented=true}));
+   Console.WriteLine("PASS real Core/Java network lifecycles; fake printer only");return 0;
+  } catch(Exception error) {
+   await File.WriteAllTextAsync(Path.Combine(folder,"result.json"),JsonSerializer.Serialize(new{success=false,stage,error=error.GetType().Name,reason=error is InvalidDataException?error.Message:null,completed=lanes.Sum(l=>l.Printer.Count)}));
+   Console.Error.WriteLine("FAIL "+stage+": "+error.GetType().Name);return 1;
+  } finally {
+   foreach(var lane in lanes)await lane.DisposeAsync();
+   await File.WriteAllTextAsync(Path.Combine(folder,"done"),"done");
+  }
+ }
+ static void Require(bool ok,string reason){if(!ok)throw new InvalidDataException(reason);}
+ sealed class Lane: IAsyncDisposable {
+  public QqqSessionClient Client{get;} public Connection Connection{get;}
+  public FakePrinter Printer{get;}=new(); public Journal Journal{get;} public List<double> Latencies{get;}=[];
+  readonly PrintApiClient api;readonly PrintWorker worker; readonly int target; readonly string root; long wakeAt; public List<double> ClaimLatency{get;}=[]; public List<double> DownloadLatency{get;}=[];
+  public Lane(QqqSessionClient client,Connection connection,string folder,int target,string root) {
+   Client=client;Connection=connection;this.target=target;this.root=root;Printer.OnDownload=()=>DownloadLatency.Add(Stopwatch.GetElapsedTime(wakeAt).TotalMilliseconds);Directory.CreateDirectory(folder);Journal=new(folder);
+   api=PrintApiClient.ForSession(client).WithRealtime(connection.Channel,connection.Settings);
+   worker=new PrintWorker(api,Printer,Journal,options:new PrintWorkerOptions{Settings=connection.Settings,StagingDirectory=Path.Combine(folder,"staging"),SynchronizeInventory=false,RecoverIncomplete=false,ActiveJobChanged=job=>{if(job is not null)ClaimLatency.Add(Stopwatch.GetElapsedTime(wakeAt).TotalMilliseconds);}});
+  }
+  public async Task Run(CancellationToken token) {
+   using var stop=CancellationTokenSource.CreateLinkedTokenSource(token);
+   Task ping=Liveness(stop.Token);
+   try {
+    while(Printer.Count<target) {
+     wakeAt=await Connection.Wakes.Reader.ReadAsync(token);
+     while(Printer.Count<target && await worker.RunOnceAsync(token)) {
+      Require(Journal.Last.Event.Status=="SPOOLED","synthetic job terminal status");
+      Latencies.Add((DateTimeOffset.UtcNow-DateTimeOffset.Parse(Journal.LastJob!.CreatedAt,CultureInfo.InvariantCulture)).TotalMilliseconds);
+      await File.WriteAllTextAsync(Path.Combine(root,"completed-"+Interlocked.Increment(ref Completed)),"acknowledged",token);
+      if(Printer.Count%25==0)await api.EventAsync(Journal.Last.JobId,Journal.Last.Event,token);
+     }
+    }
+   } finally {await stop.CancelAsync();try{await ping;}catch(OperationCanceledException){}}
+  }
+  async Task Liveness(CancellationToken token) {
+   using var tick=new PeriodicTimer(TimeSpan.FromSeconds(Connection.Settings.HeartbeatIntervalSeconds));
+   while(await tick.WaitForNextTickAsync(token))await Connection.Channel.SendAsync("PING",new{},token:token);
+  }
+  public async ValueTask DisposeAsync(){api.Dispose();await Connection.DisposeAsync();Client.Dispose();Journal.Dispose();}
+ }
+ sealed class FakePrinter:IFilePrinterBackend {
+  readonly HashSet<string> seen=new(StringComparer.Ordinal);public int Count=>seen.Count; public Action? OnDownload{get;set;}
+  public IReadOnlyList<PrinterInfo> Discover()=>[new("synthetic","No physical printer","fixture","none","READY",["ZPL"])];
+  public async Task<string> PrintFileAsync(PrintJob job,string path,CancellationToken token) {OnDownload?.Invoke();return await PrintAsync(job,await File.ReadAllBytesAsync(path,token),token);}
+  public Task<string> PrintAsync(PrintJob job,byte[] content,CancellationToken token) {
+   Require(content.AsSpan().SequenceEqual(Expected),"downloaded bytes exact");Require(seen.Add(job.JobId),"no duplicate physical action");return Task.FromResult("synthetic-"+Count);
+  }
+ }
+ // Fixture journal is deliberately separate from the installed Windows SQLite journal.
+ sealed class Journal: IJobJournal,IDisposable {
+  readonly Dictionary<string,string> states=new(StringComparer.Ordinal);readonly Dictionary<string,(string,PrintEvent)> pending=new(StringComparer.Ordinal);readonly StreamWriter log;
+  public PrintJob? LastJob{get;private set;}public (string JobId,PrintEvent Event) Last{get;private set;}
+  public Journal(string folder){log=new StreamWriter(new FileStream(Path.Combine(folder,"synthetic-receipts.jsonl"),FileMode.CreateNew,FileAccess.Write,FileShare.Read)){AutoFlush=true};}
+  public void TrackJob(PrintJob job,string? printer){LastJob=job;}
+  public string? GetState(string id)=>states.GetValueOrDefault(id);
+  public void Record(string id,PrintEvent evt){log.WriteLine(JsonSerializer.Serialize(new{jobId=id,@event=evt}));states[id]=evt.Status;pending.Add(evt.EventId,(id,evt));Last=(id,evt);}
+  public IReadOnlyList<(string JobId,PrintEvent Event)> Pending()=>pending.Values.ToList();
+  public void Acknowledge(string id){pending.Remove(id);}
+  public IReadOnlyList<(string JobId,string State)> Incomplete()=>[];
+  public void Dispose()=>log.Dispose();
+ }
+ sealed class Connection:IAsyncDisposable {
+  public required PrintingRealtimeChannel Channel{get;init;}public required Task Reader{get;init;}public required CancellationTokenSource Lifetime{get;init;}
+  public required Channel<RealtimeEnvelope> Messages{get;init;}public required Channel<long> Wakes{get;init;}public RealtimeSettings Settings{get;private set;}=new();
+  public static async Task<Connection> Open(QqqSessionClient client,CancellationToken token) {
+   var lifetime=CancellationTokenSource.CreateLinkedTokenSource(token);WebSocket socket=await client.ConnectPrintingAsync(TimeSpan.FromSeconds(20),TimeSpan.FromSeconds(60),token);
+   var channel=new PrintingRealtimeChannel(socket,new RealtimeSettings());var messages=System.Threading.Channels.Channel.CreateBounded<RealtimeEnvelope>(8);
+   var wakes=System.Threading.Channels.Channel.CreateBounded<long>(new BoundedChannelOptions(1){FullMode=BoundedChannelFullMode.DropWrite});
+   Task reader=channel.RunAsync(e=>{
+    if(e.Type=="JOB_AVAILABLE"){wakes.Writer.TryWrite(Stopwatch.GetTimestamp());return;}
+    if(e.Type is "SETTINGS" or "DESIRED_STATE") {long revision=e.Payload.GetProperty("revision").GetInt64();if(revision!=0)throw new InvalidDataException("Unexpected policy change");return;}
+    if(e.Type is "PONG" or "ACK")return;
+    if(!messages.Writer.TryWrite(e))throw new IOException("Fixture envelope inbox full");
+   },lifetime.Token);
+   _=reader.ContinueWith(t=>{wakes.Writer.TryComplete(t.Exception);messages.Writer.TryComplete(t.Exception);},TaskScheduler.Default);
+   var result=new Connection{Channel=channel,Reader=reader,Lifetime=lifetime,Messages=messages,Wakes=wakes};
+   await channel.SendAsync("HELLO",new{agentVersion=PrintApiClient.AgentVersion,capabilities=new[]{"realtime-v1","REFRESH_INVENTORY","CANCEL_SPOOL"},lastAppliedRevision=0,lastSettingsRevision=0,limits=RealtimeSettings.ClientLimits},token:token);
+   RealtimeEnvelope welcome=await messages.Reader.ReadAsync(token);Require(welcome.Type=="WELCOME","welcome");
+   result.Settings=welcome.Payload.GetProperty("settings").Deserialize<RealtimeSettings>(PrintApiClient.JsonOptions)!;result.Settings.Validate();channel.UpdateSettings(result.Settings);
+   await channel.SendAsync("STATE_APPLIED",new{lastAppliedRevision=welcome.Payload.GetProperty("desiredState").GetProperty("revision").GetInt64(),lastSettingsRevision=result.Settings.Revision},acknowledged:true,token:token);return result;
+  }
+  public async ValueTask DisposeAsync(){await Lifetime.CancelAsync();try{await Reader;}catch(Exception e)when(e is OperationCanceledException or IOException or WebSocketException){}Channel.Dispose();Lifetime.Dispose();}
+ }
+}

dev/client/Workload.csproj

@@ -0,0 +1,15 @@
+<!--
+  Copyright 2026 Kingsrook, LLC
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType><TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings><Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="Qqq.PrintAgent.Core"><HintPath>/core/Qqq.PrintAgent.Core.dll</HintPath></Reference>
+  </ItemGroup>
+</Project>

dev/client/WorkloadDiscovery.cs

@@ -0,0 +1,19 @@
+// Copyright 2026 Kingsrook, LLC
+
+// SPDX-License-Identifier: Apache-2.0
+using Qqq.PrintAgent.Core.Authentication;
+
+internal static class WorkloadDiscovery
+{
+   internal static async Task<QqqApiDiscovery> DiscoverRealtimeAsync(QqqSessionClient client, CancellationToken cancellationToken)
+   {
+      QqqApiDiscovery discovery = await client.DiscoverAsync(cancellationToken);
+      // Core discovery validates strict stable SemVer; realtime uses the same major gate as ConnectPrintingAsync.
+      QqqApiDiscovery.Extension extension = discovery.Extensions.Single(item => string.Equals(item.Name, "printing", StringComparison.Ordinal));
+      if(!Version.TryParse(extension.Version, out Version? version) || version.Major != 2)
+      {
+         throw new InvalidDataException("Native realtime printing API required.");
+      }
+      return discovery;
+   }
+}

dev/compose.authentik.yaml

@@ -0,0 +1,80 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+# Optional real provider reference. No Docker socket or published database port.
+services:
+  authentik-postgres:
+    profiles: [auth]
+    platform: linux/amd64
+    image: postgres@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea
+    environment:
+      POSTGRES_DB: authentik
+      POSTGRES_USER: authentik
+      POSTGRES_PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:?Run the development initializer first}
+    volumes:
+      - authentik-database:/var/lib/postgresql/data
+    healthcheck:
+      test: [CMD-SHELL, "pg_isready -U authentik -d authentik"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first}
+    mem_limit: 512m
+    cpus: 1.0
+
+  authentik-server:
+    profiles: [auth]
+    platform: linux/amd64
+    image: ghcr.io/goauthentik/server@sha256:602227a86455d6772e3d16b7d852713c4f864f40df5df894abd1285bb53979a5
+    command: server
+    depends_on:
+      authentik-postgres:
+        condition: service_healthy
+    environment: &authentik-environment
+      AUTHENTIK_POSTGRESQL__HOST: authentik-postgres
+      AUTHENTIK_POSTGRESQL__NAME: authentik
+      AUTHENTIK_POSTGRESQL__USER: authentik
+      AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:?Run the development initializer first}
+      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?Run the development initializer first}
+      AUTHENTIK_ERROR_REPORTING__ENABLED: "false"
+      AUTHENTIK_DISABLE_UPDATE_CHECK: "true"
+      AUTHENTIK_LOG_LEVEL: warning
+    ports:
+      - "127.0.0.1:${AUTHENTIK_HTTP_PORT:-19010}:9000"
+    volumes:
+      - authentik-data:/data
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first}
+    shm_size: 256mb
+    mem_limit: 1536m
+    cpus: 2.0
+
+  authentik-worker:
+    profiles: [auth]
+    platform: linux/amd64
+    image: ghcr.io/goauthentik/server@sha256:602227a86455d6772e3d16b7d852713c4f864f40df5df894abd1285bb53979a5
+    command: worker
+    depends_on:
+      authentik-postgres:
+        condition: service_healthy
+    environment:
+      <<: *authentik-environment
+      AUTHENTIK_BOOTSTRAP_PASSWORD_HASH: ${AUTHENTIK_BOOTSTRAP_PASSWORD_HASH:?Run the development initializer first}
+      AUTHENTIK_BOOTSTRAP_TOKEN: ${AUTHENTIK_BOOTSTRAP_TOKEN:?Run the development initializer first}
+      AUTHENTIK_BOOTSTRAP_EMAIL: developer@example.invalid
+    volumes:
+      - authentik-data:/data
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first}
+    shm_size: 256mb
+    mem_limit: 1536m
+    cpus: 2.0
+
+volumes:
+  authentik-database:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first}
+  authentik-data:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first}

dev/compose.native-auth.yaml

@@ -0,0 +1,78 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+# Opt-in unpublished core qualification. No service is a replacement for the
+# released RC.20 TABLE development host or an installed printing deployment.
+services:
+  authentik-server:
+    networks:
+      default:
+        aliases:
+          - auth.printing.internal
+          - qqq.printing.internal
+          - callback.printing.internal
+
+  native-tls:
+    profiles: [native-auth]
+    image: caddy@sha256:5f5c8640aae01df9654968d946d8f1a56c497f1dd5c5cda4cf95ab7c14d58648
+    platform: linux/amd64
+    network_mode: service:authentik-server
+    depends_on: [authentik-server]
+    volumes:
+      - ${DEV_SOURCE_DIR}/dev/native-auth/Caddyfile:/etc/caddy/Caddyfile:ro
+      - ${DEV_SOURCE_DIR}/dev/native-auth/copy-root.sh:/etc/caddy/copy-root.sh:ro
+      - native-ca:/data
+      - native-trust:/trust
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+    cpus: 1
+    mem_limit: 256m
+
+  native-qqq:
+    profiles: [native-auth]
+    build:
+      context: ${DEV_SOURCE_DIR}
+      dockerfile: dev/native-auth/Dockerfile.server
+    image: ${PRINTING_DEV_PROJECT}-native-server:local
+    environment:
+      NATIVE_QQQ_PORT: "19082"
+      NATIVE_QQQ_ORIGIN: https://qqq.printing.internal
+      NATIVE_QQQ_DATABASE_PASSWORD: ${NATIVE_QQQ_DATABASE_PASSWORD:?Initialize experimental state first}
+      NATIVE_QQQ_REFRESH_KEY: ${NATIVE_QQQ_REFRESH_KEY:?Initialize experimental state first}
+      NATIVE_AUTH_ISSUER: ${NATIVE_AUTH_ISSUER:?Initialize experimental state first}
+      NATIVE_AUTH_CLIENT_ID: ${NATIVE_AUTH_CLIENT_ID:?Initialize experimental state first}
+      NATIVE_AUTH_CLIENT_SECRET: ${NATIVE_AUTH_CLIENT_SECRET:?Initialize experimental state first}
+      NATIVE_AUTH_REDIRECT_URI: https://callback.printing.internal/oauth/callback
+    volumes:
+      - native-trust:/trust:ro
+      - native-qqq-data:/data
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+    cpus: 2
+    mem_limit: 1g
+
+  native-client:
+    profiles: [native-auth]
+    build:
+      context: ${DEV_SOURCE_DIR}
+      dockerfile: dev/native-auth/Dockerfile.client
+    image: ${PRINTING_DEV_PROJECT}-native-client:local
+    volumes:
+      - native-trust:/trust:ro
+      - ${NATIVE_AUTH_INPUT_FILE:?Initialize experimental state first}:/work/input.json:ro
+      - ${NATIVE_AUTH_RESULT_FILE:?Initialize experimental state first}:/work/result.json
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+    cpus: 2
+    mem_limit: 512m
+
+volumes:
+  native-ca:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+  native-trust:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+  native-qqq-data:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}

dev/compose.yaml

@@ -0,0 +1,108 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+# Every published port is bound to host loopback; no live printing configuration is imported.
+x-owned: &owned
+  labels:
+    io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?owned project required}
+  restart: "no"
+  cpus: 2
+  mem_limit: 1g
+  pids_limit: 256
+  cap_drop: [ALL]
+  security_opt: [no-new-privileges:true]
+  read_only: true
+  tmpfs: ["/tmp:rw,noexec,nosuid,size=128m,mode=1777"]
+
+services:
+  minio:
+    <<: *owned
+    image: cgr.dev/chainguard/minio@sha256:dc455cdd4db6e390b1b26514f15ff37681a777bf8dab41aac445a0259f751e56
+    user: "0:0"
+    command: [server, /data, --address, ":9000"]
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:?fixture secret required}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?fixture secret required}
+    volumes: [minio-data:/data]
+    ports:
+      - "127.0.0.1:${MINIO_HTTP_PORT:-19095}:9000"
+      - "127.0.0.1:${QQQ_HTTP_PORT:-19081}:${QQQ_HTTP_PORT:-19081}"
+  qqq:
+    <<: *owned
+    build:
+      context: ${DEV_SOURCE_DIR:?source required}
+      dockerfile: dev/Dockerfile.server
+      args:
+        SOURCE_COMMIT: ${SOURCE_COMMIT:?source identity required}
+    image: ${PRINTING_DEV_PROJECT}-server:local
+    network_mode: service:minio
+    depends_on: [minio]
+    environment:
+      QQQ_HTTP_PORT: ${QQQ_HTTP_PORT:-19081}
+      QQQ_DATABASE_PASSWORD: ${QQQ_DATABASE_PASSWORD:?fixture secret required}
+      QQQ_ADMIN_PASSWORD: ${QQQ_ADMIN_PASSWORD:?fixture secret required}
+      QQQ_MANAGEMENT_TOKEN: ${QQQ_MANAGEMENT_TOKEN:?fixture secret required}
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
+    volumes: [qqq-data:/data]
+  minio-test:
+    <<: *owned
+    profiles: [test]
+    image: cgr.dev/chainguard/minio@sha256:dc455cdd4db6e390b1b26514f15ff37681a777bf8dab41aac445a0259f751e56
+    user: "0:0"
+    command: [server, /data, --address, ":9000"]
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
+    tmpfs: ["/tmp:rw,noexec,nosuid,size=64m,mode=1777", "/data:rw,noexec,nosuid,size=900m,mode=1777"]
+  test-server:
+    <<: *owned
+    profiles: [test]
+    build:
+      context: ${DEV_SOURCE_DIR}
+      dockerfile: dev/Dockerfile.server
+      args:
+        SOURCE_COMMIT: ${SOURCE_COMMIT}
+    image: ${PRINTING_DEV_PROJECT}-server:local
+    network_mode: service:minio-test
+    depends_on: [minio-test]
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
+      TEST_RUN: ${TEST_RUN:-run-uninitialized}
+      WORKLOAD_MODE: ${WORKLOAD_MODE:-idle}
+    volumes: [test-data:/work]
+    entrypoint: [/bin/sh, /app/run-tests.sh]
+    healthcheck:
+      test: [CMD-SHELL, 'test -f "/work/$$TEST_RUN/input.json"']
+      interval: 1s
+      timeout: 2s
+      retries: 120
+  test-client:
+    <<: *owned
+    profiles: [test]
+    build:
+      context: ${DEV_SOURCE_DIR}
+      dockerfile: dev/Dockerfile.client
+    image: ${PRINTING_DEV_PROJECT}-client:local
+    network_mode: service:minio-test
+    depends_on:
+      test-server:
+        condition: service_healthy
+    volumes: [test-data:/work]
+    command: ["/work/${TEST_RUN:-run-uninitialized}"]
+
+volumes:
+  minio-data:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+  qqq-data:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+  test-data:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}
+networks:
+  default:
+    labels:
+      io.qrun.printing.dev: ${PRINTING_DEV_PROJECT}

dev/java/DevHost.java

@@ -0,0 +1,145 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// SPDX-License-Identifier: Apache-2.0
+package com.kingsrook.qbits.printing;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.module.filesystem.base.model.metadata.Cardinality;
+import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3BackendMetaData;
+import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3TableBackendDetails;
+import com.kingsrook.qqq.backend.module.filesystem.s3.utils.S3ClientFactory;
+import com.kingsrook.qqq.middleware.javalin.QApplicationLauncher;
+import com.kingsrook.qqq.middleware.javalin.QApplicationLauncherConfig;
+import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
+import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
+import software.amazon.awssdk.services.s3.model.S3Exception;
+
+/** Docker-only developer host. Compose publishes its port to host loopback only. */
+public final class DevHost extends PrintingLocalHost
+{
+   private static final String TABLE = "printing_documents";
+
+   private DevHost() throws Exception
+   {
+      super(new PrintingLocalSettings("jdbc:h2:file:/data/printing", "sa", required("QQQ_DATABASE_PASSWORD"), "development",
+         Integer.parseInt(required("QQQ_HTTP_PORT")), required("QQQ_MANAGEMENT_TOKEN"), "developer", required("QQQ_ADMIN_PASSWORD")));
+   }
+
+   public static void main(String[] args) throws Exception
+   {
+      waitStorage();
+      if(args.length == 1 && "--wait-storage".equals(args[0]))
+      {
+         return;
+      }
+      DevHost host = new DevHost();
+      QApplicationLauncher.run(host, new QApplicationLauncherConfig().withServerCustomizer(server ->
+      {
+         host.configure(server, true);
+         // Container interface only. The immutable Compose mapping binds host 127.0.0.1.
+         var original = server.getJavalinConfigCustomizer();
+         server.withJavalinConfigCustomizer(config ->
+         {
+            original.accept(config);
+            config.jetty.host = "0.0.0.0";
+         });
+      }));
+   }
+
+   @Override
+   public QInstance defineQInstance() throws QException
+   {
+      QInstance instance = super.defineQInstance();
+      S3BackendMetaData backend = new S3BackendMetaData().withName("printing_development_storage").withBucketName("printing-development")
+         .withEndpoint("http://127.0.0.1:9000").withPathStyleAccess(true).withRegion("us-east-1")
+         .withAccessKey(required("MINIO_ROOT_USER")).withSecretKey(required("MINIO_ROOT_PASSWORD"));
+      backend.setConnectTimeoutMillis(3000);
+      backend.setSocketTimeoutMillis(15000);
+      instance.addBackend(backend);
+      instance.addTable(new QTableMetaData().withName(TABLE).withBackendName(backend.getName())
+         .withBackendDetails(new S3TableBackendDetails().withCardinality(Cardinality.ONE).withFileNameFieldName("id").withContentsFieldName("content"))
+         .withPrimaryKeyField("id").withField(new QFieldMetaData("id", QFieldType.STRING)).withField(new QFieldMetaData("content", QFieldType.BLOB)));
+      var storage = S3ClientFactory.getClient(backend);
+      {
+         try
+         {
+            storage.headBucket(HeadBucketRequest.builder().bucket("printing-development").build());
+         }
+         catch(S3Exception missing)
+         {
+            if(missing.statusCode() != 404)
+            {
+               throw missing;
+            }
+            storage.createBucket(CreateBucketRequest.builder().bucket("printing-development").build());
+         }
+      }
+      PrintingQBitConfig config = instance.getQBits().values().stream().map(value -> value.getConfig())
+         .filter(PrintingQBitConfig.class::isInstance).map(PrintingQBitConfig.class::cast).findFirst().orElseThrow();
+      config.withStorageTableName(TABLE);
+      config.getService().configureStorage(instance, TABLE);
+      return instance;
+   }
+
+   private static void waitStorage() throws Exception
+   {
+      try(HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(2)).build())
+      {
+         long deadline = System.nanoTime() + Duration.ofSeconds(60).toNanos();
+         while(System.nanoTime() < deadline)
+         {
+            try
+            {
+               if(client.send(HttpRequest.newBuilder(URI.create("http://127.0.0.1:9000/minio/health/live"))
+                  .timeout(Duration.ofSeconds(2)).GET().build(), HttpResponse.BodyHandlers.discarding()).statusCode() == 200)
+               {
+                  return;
+               }
+            }
+            catch(java.io.IOException notReady)
+            {
+               // Only the fixture startup window retries; application work is never retried here.
+            }
+            Thread.sleep(200);
+         }
+         throw new IllegalStateException("Owned MinIO startup timed out");
+      }
+   }
+
+   private static String required(String name)
+   {
+      String value = System.getenv(name);
+      if(value == null || value.isBlank())
+      {
+         throw new IllegalArgumentException("Missing development environment setting: " + name);
+      }
+      return value;
+   }
+}

dev/java/S3PrintingQualification.java

@@ -0,0 +1,220 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// SPDX-License-Identifier: Apache-2.0
+import com.kingsrook.qbits.printing.*;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.metadata.*;
+import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.*;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.*;
+import com.kingsrook.qqq.backend.module.filesystem.base.model.metadata.Cardinality;
+import com.kingsrook.qqq.backend.module.filesystem.s3.utils.S3ClientFactory;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.*;
+import java.security.MessageDigest;
+import java.sql.*;
+import java.time.Instant;
+import java.util.*;
+import org.json.*;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.*;
+
+/** Non-listening synthetic harness. Never routes work to a Windows device. */
+public final class S3PrintingQualification {
+  private static final String TABLE = "printing_documents";
+  private static final JSONArray CHECKS = new JSONArray();
+  private static final JSONArray DOCUMENTS = new JSONArray();
+  private static final Map<String, String> OBJECT_KEYS = new HashMap<>();
+  private static DriverDataSource database;
+  private static S3Client s3;
+  private static String bucket;
+  private static String otherBucket;
+
+  public static void main(String[] args) throws Exception {
+    Path output = Path.of(args[0]).toAbsolutePath();
+    Files.createDirectories(output);
+    String run = args[2];
+    bucket = "printing-fixture-" + run;
+    otherBucket = "printing-canary-" + run;
+    S3BackendMetaData backend = new S3BackendMetaData().withName("printing_s3_" + run)
+      .withBucketName(bucket).withEndpoint(args[1]).withPathStyleAccess(true).withRegion("us-east-1")
+      .withAccessKey(System.getenv("MINIO_ROOT_USER")).withSecretKey(System.getenv("MINIO_ROOT_PASSWORD"));
+    backend.setConnectTimeoutMillis(3000);
+    backend.setSocketTimeoutMillis(15000);
+    QInstance instance = new QInstance();
+    // Required metadata only: this harness opens no HTTP endpoint or user session.
+    instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("fixture").withType(QAuthenticationType.MOCK));
+    instance.addBackend(backend);
+    instance.addTable(new QTableMetaData().withName(TABLE).withBackendName(backend.getName())
+      .withBackendDetails(new S3TableBackendDetails().withCardinality(Cardinality.ONE)
+        .withFileNameFieldName("id").withContentsFieldName("content")).withPrimaryKeyField("id")
+      .withField(new QFieldMetaData("id", QFieldType.STRING)).withField(new QFieldMetaData("content", QFieldType.BLOB)));
+    database = new DriverDataSource("jdbc:h2:file:" + output.resolve("synthetic-data").toString().replace('\\', '/'), "sa", "");
+    try {
+      s3 = S3ClientFactory.getClient(backend);
+      s3.createBucket(CreateBucketRequest.builder().bucket(bucket).build());
+      s3.createBucket(CreateBucketRequest.builder().bucket(otherBucket).build());
+      s3.putObject(PutObjectRequest.builder().bucket(bucket).key("unrelated/canary.txt").build(), RequestBody.fromString("synthetic unrelated object"));
+      s3.putObject(PutObjectRequest.builder().bucket(otherBucket).key("canary.txt").build(), RequestBody.fromString("synthetic separate bucket"));
+      PrintingService a = service(instance, "fixture-tenant-a");
+      PrintingService b = service(instance, "fixture-tenant-b");
+      String deviceA = enroll(a);
+      String deviceB = enroll(b);
+      byte[] pdf = PrintingTestDocuments.pdf();
+      byte[] zpl = "^XA^FO20,20^ADN,30,18^FDSYNTHETIC STORAGE TEST ONLY^FS^XZ".getBytes(StandardCharsets.US_ASCII);
+      byte[] large = new byte[6 * 1024 * 1024 + 71];
+      Arrays.fill(large, (byte)'A');
+      System.arraycopy("^XA^FX".getBytes(StandardCharsets.US_ASCII), 0, large, 0, 6);
+      System.arraycopy("^FS^XZ".getBytes(StandardCharsets.US_ASCII), 0, large, large.length - 6, 6);
+      String pdfJob = submitCheck(a, deviceA, "small-pdf", "PDF", pdf, false);
+      finish(a, deviceA, pdfJob, "SPOOLED");
+      String zplJob = submitCheck(a, deviceA, "small-zpl", "ZPL", zpl, false);
+      finish(a, deviceA, zplJob, "SPOOLED");
+      String largeJob = submitCheck(a, deviceA, "multipart-zpl", "ZPL", large, true);
+      finish(a, deviceA, largeJob, "SPOOLED");
+      String foreignJob = submitCheck(b, deviceB, "foreign-zpl", "ZPL", zpl, false);
+      finish(b, deviceB, foreignJob, "SPOOLED");
+      String foreignRef = reference(foreignJob);
+      String ownRef = reference(pdfJob);
+      check(!ownRef.split("/")[1].equals(foreignRef.split("/")[1]), "tenant prefixes differ");
+      expectStatus(404, () -> a.content(deviceA, foreignJob), "foreign tenant job download denied");
+      expectStatus(404, () -> a.content(deviceB, foreignJob), "foreign tenant device rejected");
+      execute("UPDATE printing_job SET content_reference=? WHERE id=?", foreignRef, pdfJob);
+      expectStatus(409, () -> a.content(deviceA, pdfJob), "foreign stored reference rejected");
+      execute("UPDATE printing_job SET content_reference=? WHERE id=?", ownRef, pdfJob);
+      check(Arrays.equals(zpl, b.content(deviceB, foreignJob)), "foreign object unchanged after rejection");
+      String failed = submitCheck(a, deviceA, "protected-failed", "ZPL", zpl, false);
+      finish(a, deviceA, failed, "FAILED");
+      String unknown = submitCheck(a, deviceA, "protected-unknown", "ZPL", zpl, false);
+      finish(a, deviceA, unknown, "OUTCOME_UNKNOWN");
+      String active = a.submit(request(deviceA, "protected-queued", "ZPL", zpl)).getString("jobId");
+      String old = Instant.now().minusSeconds(400L * 86400).toString();
+      for(String id : List.of(pdfJob, largeJob, foreignJob, failed, unknown, active)) {
+        execute("UPDATE printing_job SET created_at=?,completed_at=? WHERE id=?", old, old, id);
+      }
+      int before = objectCount();
+      check(a.runRetention() == 2, "tenant A retention removes exactly two aged successful documents");
+      check(objectCount() == before - 2, "object count reflects exact two removals");
+      missing(OBJECT_KEYS.get(ownRef));
+      missing(OBJECT_KEYS.get(reference(largeJob)));
+      expectStatus(410, () -> a.content(deviceA, pdfJob), "expired document returns 410");
+      check(a.submit(request(deviceA, "small-pdf", "PDF", pdf)).getString("jobId").equals(pdfJob), "idempotent replay survives retention without reupload");
+      check(objectCount() == before - 2, "post-retention replay creates no object");
+      for(String id : List.of(zplJob, foreignJob, failed, unknown, active)) {
+        check(s3.headObject(HeadObjectRequest.builder().bucket(bucket).key(objectKey(reference(id))).build()).contentLength() == zpl.length,
+          "protected object retained: " + status(id));
+      }
+      check(s3.getObjectAsBytes(GetObjectRequest.builder().bucket(bucket).key("unrelated/canary.txt").build()).asUtf8String().equals("synthetic unrelated object"), "unrelated same-bucket canary preserved");
+      check(s3.getObjectAsBytes(GetObjectRequest.builder().bucket(otherBucket).key("canary.txt").build()).asUtf8String().equals("synthetic separate bucket"), "separate bucket canary preserved");
+      check(a.runRetention() == 0, "repeated cleanup is idempotent");
+      check(b.runRetention() == 1, "tenant B cleanup independently removes its one eligible document");
+      check(s3.listMultipartUploads(ListMultipartUploadsRequest.builder().bucket(bucket).build()).uploads().isEmpty(), "no incomplete multipart uploads remain");
+      check(QContext.getQSession() == null, "storage restores original absent QQQ session");
+      JSONObject result = new JSONObject().put("passed", true).put("timestamp", Instant.now().toString())
+        .put("checks", CHECKS).put("documents", DOCUMENTS).put("runtimeJarCount", 204)
+        .put("appRevision", System.getenv("PRINTING_SOURCE_COMMIT"))
+        .put("h2Version", org.h2.engine.Constants.VERSION).put("retentionDays", a.getRetentionSettings().getInt("days"))
+        .put("transport", "loopback HTTP S3-compatible only").put("hardwarePrinting", false)
+        .put("qualifies", "QQQ StorageAction / AWS SDK v2 S3 data-plane behavior against disposable MinIO")
+        .put("doesNotQualify", new JSONArray(List.of("AWS IAM", "remote TLS", "production bucket ownership", "Object Lock/version lifecycle", "remote deployment", "hardware printing")));
+      Files.writeString(output.resolve("results.json"), result.toString(2) + "\n");
+      System.out.println("PASS " + CHECKS.length() + " checks; " + DOCUMENTS.length() + " synthetic document round trips");
+    } finally {
+      Files.writeString(output.resolve("completed-checks.json"), new JSONObject().put("checks", CHECKS).put("documents", DOCUMENTS).toString(2) + "\n");
+      S3ClientFactory.clearCache();
+      QContext.clear();
+    }
+  }
+  private static PrintingService service(QInstance instance, String tenant) throws Exception {
+    PrintingService service = new PrintingService(database, tenant);
+    service.initialize(); service.configureStorage(instance, TABLE); return service;
+  }
+  private static String enroll(PrintingService service) throws Exception {
+    String id = service.enroll(service.createEnrollment("fixture", "Synthetic station")
+      .put("deviceName", "Synthetic station").put("agentVersion", "isolated-storage-fixture")).getString("deviceId");
+    service.inventory(id, new JSONArray().put(new JSONObject().put("printerId", "synthetic-never-dispatched")
+      .put("name", "Synthetic storage-only destination").put("status", "READY").put("formats", new JSONArray(List.of("PDF", "ZPL")))));
+    service.enablePrinter(id, "synthetic-never-dispatched", true); return id;
+  }
+  private static JSONObject request(String device, String key, String format, byte[] bytes) {
+    return new JSONObject().put("deviceId", device).put("printerId", "synthetic-never-dispatched").put("title", "Synthetic storage qualification")
+      .put("format", format).put("contentBase64", Base64.getEncoder().encodeToString(bytes)).put("idempotencyKey", key);
+  }
+  private static String submitCheck(PrintingService service, String device, String key, String format, byte[] bytes, boolean multipart) throws Exception {
+    JSONObject request = request(device, key, format, bytes);
+    String id = service.submit(request).getString("jobId");
+    int count = objectCount();
+    check(id.equals(service.submit(request).getString("jobId")) && count == objectCount(), key + " stable replay creates no object");
+    check(service.claim(device).getJSONObject("job").getString("jobId").equals(id), key + " claimed through production service");
+    byte[] actual = service.content(device, id);
+    check(Arrays.equals(bytes, actual) && sha(bytes).equals(sha(actual)), key + " download bytes and SHA256 match");
+    String ref = reference(id);
+    String actualKey = objectKey(ref);
+    HeadObjectResponse head = s3.headObject(HeadObjectRequest.builder().bucket(bucket).key(actualKey).build());
+    check(head.contentLength() == bytes.length, key + " object length exact");
+    check(head.contentType().equals(format.equals("PDF") ? "application/pdf" : "application/vnd.zebra-zpl"), key + " content type correct");
+    check(head.eTag().contains("-2") == multipart, key + " expected single/multipart object ETag");
+    try(var c = database.getConnection(); var statement = c.prepareStatement("SELECT content_base64,content_storage_table FROM printing_job WHERE id=?")) {
+      statement.setString(1, id); try(var rows = statement.executeQuery()) { check(rows.next() && rows.getString(1) == null && TABLE.equals(rows.getString(2)), key + " payload external, no inline database copy"); }
+    }
+    DOCUMENTS.put(new JSONObject().put("case", key).put("format", format).put("bytes", bytes.length).put("sha256", sha(bytes)).put("multipart", multipart).put("etag", head.eTag())
+      .put("objectKeyEqualsStoredReference", actualKey.equals(ref)).put("objectKeyPrefixBeforeReference", actualKey.substring(0, actualKey.length() - ref.length())));
+    return id;
+  }
+  private static void finish(PrintingService service, String device, String id, String status) throws Exception {
+    for(String phase : List.of("RECEIVED", "SUBMITTING", status)) service.event(device, id, new JSONObject().put("eventId", UUID.randomUUID().toString()).put("status", phase).put("message", "Synthetic receipt; no physical device or spooler used"));
+  }
+  private static String sha(byte[] bytes) throws Exception { return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(bytes)); }
+  private static int objectCount() { return s3.listObjectsV2(ListObjectsV2Request.builder().bucket(bucket).build()).contents().size(); }
+  private static String objectKey(String reference) {
+    String known = OBJECT_KEYS.get(reference);
+    if(known != null) return known;
+    List<String> matches = s3.listObjectsV2(ListObjectsV2Request.builder().bucket(bucket).build()).contents().stream()
+      .map(S3Object::key).filter(key -> key.endsWith(reference)).toList();
+    if(matches.size() != 1) throw new AssertionError("Expected exactly one synthetic object for stored reference");
+    String key = matches.getFirst();
+    String prefix = key.substring(0, key.length() - reference.length());
+    if(!prefix.isEmpty() && !prefix.matches("\\\\+")) throw new AssertionError("Unexpected physical S3 key prefix");
+    OBJECT_KEYS.put(reference, key);
+    return key;
+  }
+  private static String reference(String id) throws Exception { return field(id, "content_reference"); }
+  private static String status(String id) throws Exception { return field(id, "status"); }
+  private static String field(String id, String field) throws Exception {
+    try(var c = database.getConnection(); var statement = c.prepareStatement("SELECT " + field + " FROM printing_job WHERE id=?")) {
+      statement.setString(1,id); try(var rows=statement.executeQuery()) { if(!rows.next()) throw new AssertionError("Missing synthetic job"); return rows.getString(1); }
+    }
+  }
+  private static void execute(String sql, String... args) throws Exception {
+    try(var c = database.getConnection(); var statement = c.prepareStatement(sql)) { for(int i=0; i<args.length; i++) statement.setString(i+1,args[i]); statement.executeUpdate(); }
+  }
+  private static void check(boolean pass, String label) { if(!pass) throw new AssertionError(label); CHECKS.put(label); }
+  private static void missing(String ref) {
+    try { s3.headObject(HeadObjectRequest.builder().bucket(bucket).key(ref).build()); throw new AssertionError("Expected removed object"); }
+    catch(S3Exception exception) { check(exception.statusCode()==404,"eligible object absent from S3 after cleanup"); }
+  }
+  @FunctionalInterface private interface Checked { void run() throws Exception; }
+  private static void expectStatus(int status, Checked operation, String label) throws Exception {
+    try { operation.run(); throw new AssertionError(label); } catch(PrintingException exception) { check(exception.getStatus()==status,label); }
+  }
+}

dev/java/WorkloadFixture.java

@@ -0,0 +1,112 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// SPDX-License-Identifier: Apache-2.0
+package com.kingsrook.qbits.printing;
+import java.nio.file.*;
+import java.nio.charset.StandardCharsets;
+import java.sql.*;
+import java.time.*;
+import java.util.*;
+import java.util.concurrent.*;
+import java.util.concurrent.atomic.AtomicReference;
+import com.kingsrook.qqq.middleware.javalin.*;
+import io.javalin.Javalin;
+import org.json.*;
+/** Fixture only: real checkout host, synthetic SDK producer, no physical printer. */
+public final class WorkloadFixture {
+ public static void main(String[] args) throws Exception {
+  Path dir=Path.of(args[0]).toAbsolutePath();
+  if(!dir.getFileName().toString().startsWith("run-"))throw new IllegalArgumentException("Owned run directory required");
+  String jdbc="jdbc:h2:file:"+dir.resolve("synthetic").toString().replace('\\','/')+";DB_CLOSE_DELAY=-1";
+  String password="synthetic-"+UUID.randomUUID();
+  List<QApplicationLauncher> launches=new ArrayList<>(); List<PrintingService> services=new ArrayList<>();
+  List<String> devices=new ArrayList<>(); JSONArray inputs=new JSONArray();
+  boolean idle=args.length>1 && args[1].equals("idle"); int total=idle?40:10000; long started=System.nanoTime(); int exit=1;
+  try {
+   for(int tenant=0;tenant<2;tenant++) {
+    PrintingLocalHost host=new PrintingLocalHost(new PrintingLocalSettings(jdbc,"sa","","tenant-"+tenant,0,"fixture-only-management-token-123456","operator",password));
+    AtomicReference<Javalin> app=new AtomicReference<>();
+    QApplicationLauncher launch=QApplicationLauncher.run(host,new QApplicationLauncherConfig().withRegisterShutdownHook(false).withServerCustomizer(server->{host.configure(server,false);server.withJavalinConfigurationCustomizer(app::set);}));
+    launches.add(launch);
+    PrintingService service=launch.getQInstance().getQBits().values().stream().map(v->v.getConfig()).filter(PrintingQBitConfig.class::isInstance).map(PrintingQBitConfig.class::cast).findFirst().orElseThrow().getService();
+    services.add(service);
+    for(int lane=0;lane<4;lane++) {
+     JSONObject enrolled=service.enrollForUser(service.createEnrollment("default","Synthetic lane").put("deviceName","Synthetic lane").put("agentVersion","qualification"),"operator");
+     String device=enrolled.getString("deviceId");devices.add(device);
+     service.inventory(device,new JSONArray().put(new JSONObject().put("printerId","synthetic").put("name","No physical printer").put("status","READY").put("formats",new JSONArray().put("ZPL"))));service.enablePrinter(device,"synthetic",true);
+     inputs.put(new JSONObject().put("origin","http://127.0.0.1:"+app.get().port()+"/").put("username","operator").put("password",password).put("tenant","tenant-"+tenant).put("deviceId",device).put("deviceToken",enrolled.getString("deviceToken")));
+    }
+   }
+   // Only synthetic credentials inside the already protected run directory.
+   Files.writeString(dir.resolve("input.json"),new JSONObject().put("lanes",inputs).put("idle",idle).put("jobsPerLane",total/8).toString());
+   await(dir.resolve("ready"),Duration.ofMinutes(2));
+   byte[] payload=("^XA^FO20,20^FDSYNTHETIC NOT PRINTED^FS"+" ".repeat(980)+"^XZ").getBytes(StandardCharsets.US_ASCII);
+   String encoded=Base64.getEncoder().encodeToString(payload);
+   long producing=System.nanoTime();
+   if(idle) { for(int job=0;job<total;job++) { int lane=job%8; PrintingService service=services.get(lane/4); JSONObject request=new JSONObject().put("deviceId",devices.get(lane)).put("printerId","synthetic").put("title","Synthetic idle workload").put("format","ZPL").put("contentBase64",encoded).put("idempotencyKey","idle-"+job); service.submit(request); await(dir.resolve("completed-"+(job+1)),Duration.ofSeconds(30)); Thread.sleep(200); } } else try(var executor=Executors.newFixedThreadPool(8)) {
+    List<Future<?>> futures=new ArrayList<>();
+    for(int lane=0;lane<8;lane++) { final int index=lane;
+     futures.add(executor.submit(()->{try{
+      PrintingService service=services.get(index/4);
+      for(int job=0;job<1250;job++) {
+       JSONObject request=new JSONObject().put("deviceId",devices.get(index)).put("printerId","synthetic").put("title","Synthetic workload "+job).put("format","ZPL").put("contentBase64",encoded).put("idempotencyKey","lane-"+index+"-"+job);
+       JSONObject submitted=service.submit(request);
+       if(job%25==0 && !submitted.getString("jobId").equals(service.submit(request).getString("jobId")))throw new IllegalStateException("Replay duplicated job");
+      }
+     }catch(Exception e){throw new RuntimeException(e);}}));
+    }
+    for(var future:futures)future.get(15,TimeUnit.MINUTES);
+   }
+   double producerSeconds=(System.nanoTime()-producing)/1e9;
+   Files.writeString(dir.resolve("producer-done"),"done");
+   await(dir.resolve("done"),Duration.ofMinutes(15));
+   JSONObject client=new JSONObject(Files.readString(dir.resolve("result.json")));
+   if(!client.getBoolean("success"))throw new IllegalStateException("Client reported failure");
+   JSONObject report=new JSONObject().put("success",true).put("jobs",total).put("receipts",total*3).put("idle",idle).put("producerSeconds",producerSeconds).put("elapsedSeconds",(System.nanoTime()-started)/1e9).put("realPrinterCalls",0);
+   try(Connection connection=DriverManager.getConnection(jdbc,"sa","");Statement query=connection.createStatement()) {
+    require(query,"SELECT COUNT(*) FROM printing_job",total);
+    require(query,"SELECT COUNT(*) FROM printing_job WHERE status='SPOOLED'",total);
+    require(query,"SELECT COUNT(*) FROM printing_event",total*3);
+    require(query,"SELECT COUNT(*) FROM printing_document_orphan",0);
+    for(int tenant=0;tenant<2;tenant++) {
+     require(query,"SELECT COUNT(*) FROM printing_job WHERE tenant_id='tenant-"+tenant+"'",total/2);
+     require(query,"SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id='tenant-"+tenant+"' AND device_id=''",(total/2L)*payload.length);
+    }
+    JSONArray cross=new JSONArray();for(int tenant=0;tenant<2;tenant++) {
+     String foreign=services.get(1-tenant).jobsPage(1,null).getJSONArray("jobs").getJSONObject(0).getString("jobId");
+     try {services.get(tenant).getJob(foreign);throw new IllegalStateException("Foreign job visible");}catch(PrintingException denied){if(denied.getStatus()!=404)throw denied;}
+     cross.put(true);
+    }
+    report.put("tenantIsolation",cross).put("retainedAccountingVerified",true).put("bytesPerDocument",payload.length);
+   }
+   Files.writeString(dir.resolve("server-result.json"),report.toString(2));exit=0;
+  } catch(Throwable failure) {
+   Files.writeString(dir.resolve("server-error.json"),new JSONObject().put("error",failure.getClass().getName()).put("cause",failure.getCause()==null?"":failure.getCause().getClass().getName()).toString());
+  } finally {
+   for(int i=launches.size()-1;i>=0;i--)launches.get(i).stop();
+   try(Connection connection=DriverManager.getConnection(jdbc,"sa","");Statement query=connection.createStatement()){query.execute("SHUTDOWN");}
+   Files.writeString(dir.resolve("stopped.json"),new JSONObject().put("normalStop",true).put("exitCode",exit).toString());
+  }
+  System.exit(exit);
+ }
+ static void await(Path file,Duration limit)throws Exception {long deadline=System.nanoTime()+limit.toNanos();while(!Files.exists(file)){if(System.nanoTime()>deadline)throw new TimeoutException("Fixture deadline");Thread.sleep(100);}}
+ static void require(Statement query,String sql,long expected)throws Exception {try(ResultSet rows=query.executeQuery(sql)){if(!rows.next()||rows.getLong(1)!=expected)throw new IllegalStateException("Synthetic count/accounting mismatch");}}
+}

dev/log4j2.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2026 Kingsrook, LLC
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+<Configuration status="ERROR">
+  <Appenders><Console name="Console" target="SYSTEM_ERR"><PatternLayout pattern="%level %logger{1}: %message%n"/></Console></Appenders>
+  <Loggers>
+    <Logger name="software.amazon.awssdk" level="OFF"/>
+    <Logger name="org.apache.http" level="OFF"/>
+    <Root level="ERROR"><AppenderRef ref="Console"/></Root>
+  </Loggers>
+</Configuration>

dev/native-auth/Caddyfile

@@ -0,0 +1,20 @@
+{
+   admin off
+   skip_install_trust
+   auto_https disable_redirects
+}
+
+https://auth.printing.internal {
+   tls internal
+   reverse_proxy 127.0.0.1:9000
+}
+
+https://qqq.printing.internal {
+   tls internal
+   reverse_proxy native-qqq:19082
+}
+
+https://callback.printing.internal {
+   tls internal
+   reverse_proxy native-client:8088
+}

dev/native-auth/Dockerfile.client

@@ -0,0 +1,22 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b AS build
+# Same exact published production Core source as the normal development workload.
+ADD --checksum=sha256:82fcdbf7240760939a63b219aeb15a2333b3a8a02b52307a8a328500fca71fb6 https://github.com/QRun-IO/qqq-print-agent/archive/346fc285198908c47a2ee9db7b9adb53d5e88c3c.tar.gz /tmp/client.tar.gz
+RUN mkdir /client && tar -xzf /tmp/client.tar.gz -C /client --strip-components=1 && rm /tmp/client.tar.gz
+RUN dotnet build /client/src/Qqq.PrintAgent.Core/Qqq.PrintAgent.Core.csproj -c Release -p:Platform=x64 -p:Version=0.3.1-rc.1 -p:RestoreLockedMode=true --nologo
+RUN mkdir /core && cp /client/src/Qqq.PrintAgent.Core/bin/x64/Release/net10.0/Qqq.PrintAgent.Core.dll /core/
+WORKDIR /fixture/dev/native-auth/client
+COPY dev/native-auth/client .
+COPY dev/client/WorkloadDiscovery.cs /fixture/dev/client/WorkloadDiscovery.cs
+RUN dotnet build -c Release --nologo -o /out
+RUN dotnet /out/NativeAuth.dll --check-discovery
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b
+WORKDIR /app
+COPY --from=build /out .
+COPY dev/native-auth/start-client.sh /app/start-client.sh
+RUN chmod 0555 /app/start-client.sh
+ENV DOTNET_EnableDiagnostics=0
+ENTRYPOINT ["/app/start-client.sh"]

dev/native-auth/Dockerfile.server

@@ -0,0 +1,29 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+FROM maven:3.9.11-eclipse-temurin-21@sha256:6fdc855a6ed81d288ca7ca37ac6ff5e9308b612485c0801d70b25a858c83d237 AS build
+# DEVELOPMENT ONLY: exact public candidate, never installed into a host Maven cache.
+ADD --checksum=sha256:d99bafdf5520d0dc039b598787c003f23505cec3a652eb8ded496a24c6ed6060 https://github.com/QRun-IO/qqq/archive/ecf0f550a0357cec6387c2b54efca128a405a629.tar.gz /tmp/core.tar.gz
+RUN mkdir /candidate && tar -xzf /tmp/core.tar.gz -C /candidate --strip-components=1 && rm /tmp/core.tar.gz
+WORKDIR /candidate
+RUN mvn -B -Dmaven.repo.local=/candidate-maven -Drevision=4.1.0-native-dev-ecf0f550 -Dmaven.test.skip=true -pl qqq-bom,qqq-backend-core,qqq-backend-module-rdbms,qqq-backend-module-filesystem,qqq-middleware-javalin -am install
+WORKDIR /printing
+COPY pom.xml mvnw ./
+COPY .mvn .mvn
+COPY checkstyle checkstyle
+COPY src src
+COPY LICENSE NOTICE ./
+RUN chmod +x mvnw && ./mvnw -B -Dmaven.repo.local=/candidate-maven -Dqqq.version=4.1.0-native-dev-ecf0f550 -Dmaven.test.skip=true package dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=target/runtime
+COPY dev/native-auth/java /fixture-src
+RUN mkdir /fixture-classes && javac -proc:none -cp 'target/classes:target/runtime/*' -d /fixture-classes /fixture-src/*.java
+
+FROM eclipse-temurin:21-jdk-jammy@sha256:742daacb9316be4b6fc60258f6e4ac2a11882f6c597373c92290a57bfad0d2e0
+WORKDIR /app
+COPY --from=build /printing/target/classes classes
+COPY --from=build /printing/target/runtime lib
+COPY --from=build /fixture-classes fixture
+COPY dev/log4j2.xml /app/log4j2.xml
+COPY dev/native-auth/start-server.sh /app/start-server.sh
+RUN chmod 0555 /app/start-server.sh
+ENV NATIVE_CORE_SOURCE=ecf0f550a0357cec6387c2b54efca128a405a629
+ENTRYPOINT ["/app/start-server.sh"]

dev/native-auth/README.md

@@ -0,0 +1,96 @@
+# Experimental native Authentik qualification
+
+This optional profile tests an **unreleased upstream QQQ candidate**. It does
+not replace the default released RC.20 TABLE/MinIO development environment,
+install a connector, or qualify the Windows browser callback UI.
+
+From the repository root, with Docker and PowerShell 7.4 or later:
+
+```powershell
+pwsh ./dev/Invoke-Dev.ps1 -Action Test -ExperimentalNativeAuth
+```
+
+The command creates a fresh owned project, builds the pinned sources, runs the
+test, and removes its containers, network and synthetic database volumes in
+`finally`. Protected input and sanitized result files remain outside the
+checkout. Do not print or commit the private input or Compose environment.
+An explicit fresh `-StateDirectory` preserves the same cleanup behavior.
+Persistent `Start` and conversion of an existing standard environment are
+refused for this profile.
+
+The test uses actual Authentik login stages with generated synthetic accounts,
+the standard QQQ OAuth2 code/session/refresh handlers, and the published .NET
+Core PKCE/session client. The provider issues the authorization codes. The
+client receives a real HTTPS callback and stores only the opaque QQQ session
+in process; provider refresh tokens remain on the QQQ server.
+
+The required checks are:
+
+- Ordinary TLS rejects the fixture before its private CA is installed.
+- Actual API discovery advertises the typed native session grant.
+- Authorized real provider login resolves a server-derived native identity.
+- A wrong-Origin cookie request and an authenticated subject without the
+  printing permission are rejected.
+- A logged-out QQQ session cannot be replayed.
+- After the 20-second provider access grant expires, standard QQQ renewal
+  obtains a new provider grant and preserves the principal and tenant.
+- Revoking the synthetic subject's provider refresh grants prevents renewal
+  after the next access-grant expiry.
+
+Success is recorded only when every check passes. A failure report contains
+the stage and exception type, without callback URLs, credentials or response
+bodies. This short renewal test does not prove months of unattended operation.
+
+Printing discovery accepts stable semantic versions in major 2, including
+2.0.0 and 2.1.0, through the same production Core validation and shared major
+gate as the default workload. The experimental upstream API must still be
+exactly 1.9.0 with `nativeSessionLogin`; typed metadata, PKCE, TLS, callback and
+permission checks are unchanged. The native-client image build runs 12 fake-HTTP
+compatibility checks before any provider or fixture input is used.
+
+## Isolation and source pins
+
+The upstream source is
+[`ecf0f550a0357cec6387c2b54efca128a405a629`](https://github.com/QRun-IO/qqq/commit/ecf0f550a0357cec6387c2b54efca128a405a629).
+Its archive checksum is pinned in `Dockerfile.server`. Maven installs the
+development build only into `/candidate-maven` inside the image; no host Maven
+cache or installed runtime is mounted or changed. Printing source is compiled
+against that candidate solely for this test.
+
+The production .NET Core client is pinned to published source
+[`346fc285198908c47a2ee9db7b9adb53d5e88c3c`](https://github.com/QRun-IO/qqq-print-agent/commit/346fc285198908c47a2ee9db7b9adb53d5e88c3c)
+with a checked archive hash. Authentik, PostgreSQL, Caddy, Java and .NET images
+are pinned by digest in the Compose files and Dockerfiles.
+
+Caddy issues the three fixture HTTPS hostnames using its private local CA.
+`skip_install_trust` prevents automatic trust installation. Only the public
+root certificate is copied to the Java and .NET containers' trust stores;
+ordinary chain and hostname validation remain enabled. CA private keys stay
+in the TLS container's owned volume. No Windows or browser trust store changes
+occur. See [Caddy's local HTTPS documentation](https://caddyserver.com/docs/automatic-https#local-https).
+
+The HTTPS callback receiver is internal to the Compose network. It is separate
+from the installed connector's private URI callback. No callback host port is
+published. The profile mounts public Caddy configuration and the two specific
+private input/result files, rather than a host home or credential directory.
+
+The QQQ fixture uses fresh standard session, redirect-state and encrypted
+refresh-token tables. Its customizer maps the verified provider's synthetic
+`printing_admin` group to the existing native permission. It creates no device
+pairing, job, print operation or fabricated user session. Released RC.20 lacks
+the native-session grant; this experiment must stay opt-in until an appropriate
+immutable upstream tuple is published and separately adopted.
+
+## Recorded local qualification
+
+On 2026-11-01 the full disposable profile passed all eight checks and exited zero.
+Independent inventory confirmed zero owned containers, volumes and networks after
+cleanup. This is evidence for the pinned experimental tuple above, not adoption
+into the default released runtime or installed Windows UI acceptance.
+
+A fresh run against server source `3592dec` (printing API 2.1.0) and the reviewed
+probe compatibility correction also passed all eight checks on 2026-11-01.
+All source files matched the pre-run hash manifest through completion, and
+independent cleanup again found no owned containers, volumes or networks.
+The native image's 12 discovery checks and default workload's nine checks pass.
+The unreleased upstream and installed-browser limitations above still apply.

dev/native-auth/client/CallbackReceiver.cs

@@ -0,0 +1,54 @@
+// Copyright 2026 Kingsrook, LLC
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Net;
+using System.Threading.Channels;
+
+namespace Printing.NativeAuth;
+
+/// <summary>Receives the actual HTTPS-proxied callback only inside this test network.</summary>
+internal sealed class CallbackReceiver : IDisposable
+{
+   private readonly HttpListener _listener = new();
+   private readonly Channel<Uri> _callbacks = Channel.CreateBounded<Uri>(1);
+   private readonly Uri _callback;
+
+   internal CallbackReceiver(Uri callback)
+   {
+      _callback = callback;
+      _listener.Prefixes.Add("http://+:8088/");
+      _listener.Start();
+      _ = ReceiveAsync();
+   }
+
+   private async Task ReceiveAsync()
+   {
+      try
+      {
+         while(_listener.IsListening)
+         {
+            HttpListenerContext context = await _listener.GetContextAsync();
+            Uri? request = context.Request.Url;
+            bool valid = request is not null && request.AbsolutePath == _callback.AbsolutePath
+               && context.Request.Headers["Host"] == _callback.Authority
+               && context.Request.Headers["X-Forwarded-Proto"] == "https"
+               && context.Request.HttpMethod == "GET" && request.Query.Length is > 0 and < 16384;
+            if(valid)
+            {
+               var actual = new UriBuilder(_callback) { Query = request!.Query.TrimStart('?') };
+               valid = _callbacks.Writer.TryWrite(actual.Uri);
+            }
+            context.Response.StatusCode = valid ? 200 : 400;
+            context.Response.ContentLength64 = 0;
+            context.Response.Close();
+         }
+      }
+      catch(Exception exception) when(exception is HttpListenerException or ObjectDisposedException)
+      {
+         _callbacks.Writer.TryComplete();
+      }
+   }
+
+   internal ValueTask<Uri> ReadAsync(CancellationToken token) => _callbacks.Reader.ReadAsync(token);
+   public void Dispose() => _listener.Close();
+}

dev/native-auth/client/FixtureHttp.cs

@@ -0,0 +1,87 @@
+// Copyright 2026 Kingsrook, LLC
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Net;
+using System.Net.Http.Headers;
+using System.Text;
+using System.Text.Json.Nodes;
+
+namespace Printing.NativeAuth;
+
+/// <summary>Small bounded fixture transport; no redirects, proxy or response-body diagnostics.</summary>
+internal sealed class FixtureHttp : IDisposable
+{
+   internal sealed record Reply(HttpStatusCode Status, JsonObject? Json, Uri? Location);
+   internal sealed record TraceEntry(string Kind, int Status, bool HasQuery, string? LocationKind, bool LocationHasQuery);
+   internal static List<TraceEntry> Trace { get; } = [];
+   internal static string? LastRequestKind { get; private set; }
+   internal static int? LastStatus { get; private set; }
+   private readonly HttpClient _client;
+   private readonly CookieContainer _cookies = new();
+   private readonly Uri _origin;
+   private readonly string? _adminToken;
+
+   internal FixtureHttp(Uri origin, bool cookies = false, string? adminToken = null)
+   {
+      _origin = origin;
+      _adminToken = adminToken;
+      _client = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseProxy = false, UseCookies = cookies, CookieContainer = _cookies })
+      {
+         Timeout = TimeSpan.FromSeconds(15),
+         MaxResponseContentBufferSize = 524288,
+      };
+   }
+
+   internal async Task<Reply> SendAsync(string method, Uri uri, JsonObject? body, CancellationToken cancellationToken)
+   {
+      if(uri.Scheme != "https" || uri.GetLeftPart(UriPartial.Authority) != _origin.GetLeftPart(UriPartial.Authority))
+      {
+         throw new InvalidOperationException("A fixture request left its configured HTTPS origin.");
+      }
+      using var request = new HttpRequestMessage(new HttpMethod(method), uri);
+      // Fixed classifications only: never retain a query, callback, identifier or body.
+      LastRequestKind = Classify(uri, method);
+      LastStatus = null;
+      if(_adminToken is not null)
+      {
+         if(!uri.AbsolutePath.StartsWith("/api/v3/", StringComparison.Ordinal)) { throw new InvalidOperationException("Administrative credential scope refused."); }
+         request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _adminToken);
+      }
+      if(body is not null)
+      {
+         request.Content = new StringContent(body.ToJsonString(), Encoding.UTF8, "application/json");
+         request.Headers.Add("Origin", _origin.GetLeftPart(UriPartial.Authority));
+         request.Headers.Referrer = _origin;
+         Cookie? csrf = _cookies.GetCookies(_origin).Cast<Cookie>().SingleOrDefault(cookie => cookie.Name == "authentik_csrf");
+         csrf ??= _cookies.GetCookies(_origin).Cast<Cookie>().SingleOrDefault(cookie => cookie.Name == "csrftoken");
+         if(csrf is not null) { request.Headers.Add("X-authentik-CSRF", csrf.Value); }
+      }
+      using HttpResponseMessage response = await _client.SendAsync(request, cancellationToken);
+      LastStatus = (int)response.StatusCode;
+      Uri? location = response.Headers.Location is null ? null : new Uri(_origin, response.Headers.Location);
+      if(Trace.Count == 32) { Trace.RemoveAt(0); }
+      Trace.Add(new TraceEntry(LastRequestKind, (int)response.StatusCode, uri.Query.Length != 0,
+         location is null ? null : Classify(location, "GET"), location?.Query.Length > 0));
+      string content = await response.Content.ReadAsStringAsync(cancellationToken);
+      JsonObject? json = response.Content.Headers.ContentType?.MediaType == "application/json" && content.Length != 0
+         ? JsonNode.Parse(content)?.AsObject() : null;
+      return new Reply(response.StatusCode, json, response.Headers.Location);
+   }
+
+   internal Task<Reply> SendAsync(string method, string path, JsonObject? body, CancellationToken cancellationToken)
+      => SendAsync(method, new Uri(_origin, path), body, cancellationToken);
+
+   private static string Classify(Uri uri, string method) => uri.Host == "callback.printing.internal" ? "callback"
+      : uri.AbsolutePath.StartsWith("/application/o/authorize", StringComparison.Ordinal) ? "provider-authorization"
+      : uri.AbsolutePath.StartsWith("/if/flow/", StringComparison.Ordinal) ? "provider-flow-page"
+      : uri.AbsolutePath.StartsWith("/api/v3/flows/executor/", StringComparison.Ordinal) ? "provider-flow-executor-" + method
+      : "fixture-api";
+
+   internal static JsonObject RequireJson(Reply reply, HttpStatusCode expected)
+   {
+      if(reply.Status != expected || reply.Json is null) { throw new InvalidOperationException("Unexpected fixture API status or document shape."); }
+      return reply.Json;
+   }
+
+   public void Dispose() => _client.Dispose();
+}

dev/native-auth/client/NativeAuth.csproj

@@ -0,0 +1,18 @@
+<!--
+  Copyright 2026 Kingsrook, LLC
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="Qqq.PrintAgent.Core"><HintPath>/core/Qqq.PrintAgent.Core.dll</HintPath></Reference>
+    <Compile Include="../../client/WorkloadDiscovery.cs" Link="WorkloadDiscovery.cs" />
+  </ItemGroup>
+</Project>

dev/native-auth/client/NativeAuthDiscovery.cs

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+using Qqq.PrintAgent.Core.Authentication;
+
+namespace Printing.NativeAuth;
+
+/// <summary>Requires the pinned experimental native grant before provider authentication.</summary>
+internal static class NativeAuthDiscovery
+{
+   /// <summary>Checks actual production discovery without sending credentials.</summary>
+   internal static async Task DiscoverAsync(QqqSessionClient client, CancellationToken token)
+   {
+      QqqApiDiscovery discovery = await WorkloadDiscovery.DiscoverRealtimeAsync(client, token);
+      if(discovery.ApiVersion != "1.9.0" || !discovery.Features.Contains("nativeSessionLogin", StringComparer.Ordinal))
+      {
+         throw new InvalidOperationException("The actual server did not advertise the pinned native-session API.");
+      }
+   }
+}

dev/native-auth/client/NativeAuthDiscoveryChecks.cs

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+using System.Net;
+using System.Text.Json;
+using Qqq.PrintAgent.Core.Authentication;
+
+namespace Printing.NativeAuth;
+
+/// <summary>Exercises the real native probe gate against bounded, credential-free HTTP responses.</summary>
+internal static class NativeAuthDiscoveryChecks
+{
+   /// <summary>Accepts compatible printing releases while preserving the exact upstream grant requirement.</summary>
+   internal static async Task RunAsync()
+   {
+      (string PrintingVersion, string ApiVersion, bool NativeGrant, bool Accepted)[] cases =
+      [
+         ("2.0.0", "1.9.0", true, true),
+         ("2.1.0", "1.9.0", true, true),
+         ("2.9.17", "1.9.0", true, true),
+         ("1.9.0", "1.9.0", true, false),
+         ("3.0.0", "1.9.0", true, false),
+         ("2.1", "1.9.0", true, false),
+         ("2.01.0", "1.9.0", true, false),
+         ("2.1.0-rc.1", "1.9.0", true, false),
+         ("not-a-version", "1.9.0", true, false),
+         ("2.1.0", "1.8.0", true, false),
+         ("2.1.0", "1.10.0", true, false),
+         ("2.1.0", "1.9.0", false, false),
+      ];
+      foreach((string printingVersion, string apiVersion, bool nativeGrant, bool expected) in cases)
+      {
+         using var handler = new DiscoveryHandler(printingVersion, apiVersion, nativeGrant);
+         using var client = new QqqSessionClient(new Uri("https://printing.example.invalid"), handler);
+         bool accepted = false;
+         try
+         {
+            await NativeAuthDiscovery.DiscoverAsync(client, CancellationToken.None);
+            accepted = true;
+         }
+         catch(QqqSessionException error) when(error.Failure == QqqSessionException.FailureKind.ConfigurationRequired)
+         {
+         }
+         catch(InvalidDataException)
+         {
+         }
+         catch(InvalidOperationException)
+         {
+         }
+         if(accepted != expected || handler.Requests != 1)
+         {
+            throw new InvalidDataException($"Native discovery compatibility case {printingVersion}/{apiVersion}/grant={nativeGrant} failed.");
+         }
+      }
+      Console.WriteLine($"Native discovery compatibility checks passed: {cases.Length}.");
+   }
+
+
+
+   /// <summary>Supplies discovery only and fails if the probe attempts authenticated traffic.</summary>
+   private sealed class DiscoveryHandler(string printingVersion, string apiVersion, bool nativeGrant) : HttpMessageHandler
+   {
+      /// <summary>Ensures rejected metadata still traversed the public HTTP discovery boundary.</summary>
+      internal int Requests { get; private set; }
+
+
+
+      /// <summary>Refuses any credential or request outside the public discovery boundary.</summary>
+      protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+      {
+         if(request.Method != HttpMethod.Get || request.RequestUri?.AbsoluteUri != "https://printing.example.invalid/qqq/v1/version"
+            || request.Headers.Contains("Cookie") || request.Headers.Contains("Authorization")
+            || request.Headers.Contains("X-QQQ-Device-Id") || request.Headers.Contains("X-QQQ-Device-Token"))
+         {
+            throw new InvalidOperationException("Native discovery must precede authentication and device proof.");
+         }
+         Requests++;
+         string[] features = nativeGrant
+            ? ["version", "metaData", "processes", "processCancel", "extensions", "widgets", "nativeSessionLogin"]
+            : ["version", "metaData", "processes", "processCancel", "extensions", "widgets"];
+         string json = JsonSerializer.Serialize(new
+         {
+            apiVersion,
+            features,
+            clientChannels = new[] { "api" },
+            extensions = new[] { new { name = "printing", version = printingVersion, pathPrefix = "/qbit/printing" } }
+         });
+         return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(json) });
+      }
+   }
+}

dev/native-auth/client/Program.cs

@@ -0,0 +1,241 @@
+// Copyright 2026 Kingsrook, LLC
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Net;
+using System.Security.Authentication;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Text.RegularExpressions;
+using Qqq.PrintAgent.Core.Authentication;
+
+namespace Printing.NativeAuth;
+
+internal static class Program
+{
+   private const string CoreSource = "ecf0f550a0357cec6387c2b54efca128a405a629";
+   private const string ClientSource = "346fc285198908c47a2ee9db7b9adb53d5e88c3c";
+   private const string InputPath = "/work/input.json";
+   private const string ResultPath = "/work/result.json";
+   private const string TlsMarker = "/tmp/printing-native-untrusted-tls-passed";
+   private static readonly List<string> Checks = [];
+   private static string _stage = "input";
+   private static bool? _authorizationRequestMatches;
+
+   public static async Task<int> Main(string[] arguments)
+   {
+      if(arguments is ["--check-discovery"])
+      {
+         await NativeAuthDiscoveryChecks.RunAsync();
+         return 0;
+      }
+      JsonObject? input = null;
+      try
+      {
+         if(arguments.Length != 1 || arguments[0] is not ("assert-untrusted" or "test"))
+         { throw new InvalidOperationException("An explicit fixture action is required."); }
+         if(new FileInfo(InputPath).Length is <= 0 or > 65536)
+         { throw new InvalidOperationException("Fixture input size is invalid."); }
+         input = JsonNode.Parse(await File.ReadAllTextAsync(InputPath))!.AsObject();
+         ValidateInput(input);
+         using var deadline = new CancellationTokenSource(TimeSpan.FromMinutes(5));
+         if(arguments[0] == "assert-untrusted")
+         {
+            _stage = "untrusted-tls";
+            await AssertUntrustedAsync(new Uri(ProviderSetup.Text(input, "providerOrigin")), deadline.Token);
+            await File.WriteAllTextAsync(TlsMarker, "passed", deadline.Token);
+            return 0;
+         }
+         if(!File.Exists(TlsMarker)) { throw new InvalidOperationException("The ordinary TLS negative control did not run."); }
+         Checks.Add("untrusted-tls-refused");
+         await QualifyAsync(input, deadline.Token);
+         await WriteResultAsync(input, "PASS", null, null);
+         Console.WriteLine("Experimental native Authentik qualification passed; development-only unpublished core.");
+         return 0;
+      }
+      catch(Exception exception)
+      {
+         // Exception messages, response bodies, callback URLs and credentials are deliberately withheld.
+         await WriteResultAsync(input, "FAILED", exception.GetType().Name,
+            exception is QqqSessionException sessionException ? sessionException.Failure.ToString() : null);
+         Console.Error.WriteLine("Experimental native Authentik qualification failed at " + _stage + " (" + exception.GetType().Name + ").");
+         return 1;
+      }
+   }
+
+   private static void ValidateInput(JsonObject input)
+   {
+      if(!Regex.IsMatch(ProviderSetup.Text(input, "project"), "^qbit-printing-dev-[a-f0-9]{32}$", RegexOptions.CultureInvariant)
+         || ProviderSetup.Text(input, "coreSource") != CoreSource || ProviderSetup.Text(input, "clientSource") != ClientSource
+         || ProviderSetup.Text(input, "providerOrigin") != "https://auth.printing.internal"
+         || ProviderSetup.Text(input, "qqqOrigin") != "https://qqq.printing.internal"
+         || ProviderSetup.Text(input, "callback") != "https://callback.printing.internal/oauth/callback"
+         || ProviderSetup.Text(input, "issuer") != "https://auth.printing.internal/application/o/" + ProviderSetup.Text(input, "project") + "/"
+         || ProviderSetup.Text(input, "clientId") != ProviderSetup.Text(input, "project"))
+      { throw new InvalidOperationException("Fixture identity or destination differs from the pinned local contract."); }
+   }
+
+   private static QqqSessionClient Session(Uri origin) => new(origin,
+      new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseProxy = false });
+
+   private static async Task AssertUntrustedAsync(Uri origin, CancellationToken token)
+   {
+      using var transport = new FixtureHttp(origin);
+      try { await transport.SendAsync("GET", "/-/health/live/", null, token); }
+      catch(HttpRequestException exception)
+      {
+         for(Exception? cause = exception; cause is not null; cause = cause.InnerException)
+         {
+            if(cause is AuthenticationException) { return; }
+         }
+         throw new InvalidOperationException("The negative TLS control failed for a reason other than certificate authentication.");
+      }
+      throw new InvalidOperationException("The test unexpectedly trusted its private CA before scoped installation.");
+   }
+
+   private static async Task QualifyAsync(JsonObject input, CancellationToken token)
+   {
+      var origin = new Uri(ProviderSetup.Text(input, "qqqOrigin"));
+      var providerOrigin = new Uri(ProviderSetup.Text(input, "providerOrigin"));
+      var callback = new Uri(ProviderSetup.Text(input, "callback"));
+      _stage = "readiness";
+      await WaitForQqqAsync(origin, token);
+      using var provider = new ProviderSetup(input);
+      _stage = "provider-readiness";
+      await provider.WaitReadyAsync(token);
+      _stage = "provider-configuration";
+      await provider.ConfigureAsync(token);
+      using var receiver = new CallbackReceiver(callback);
+      using var first = Session(origin);
+      _stage = "typed-native-discovery";
+      await NativeAuthDiscovery.DiscoverAsync(first, token);
+      QqqAuthenticationMetadata metadata = await first.GetAuthenticationMetadataAsync(token);
+      if(metadata.Values?.ClientId != ProviderSetup.Text(input, "clientId"))
+      { throw new InvalidOperationException("Native metadata did not retain the configured client identifier."); }
+      Checks.Add("typed-native-grant");
+
+      _stage = "real-provider-login";
+      await LoginAsync(first, receiver, input, providerOrigin, callback, authorized: true, token);
+      _stage = "authorized-native-identity";
+      QqqSessionBinding identity = await first.GetSessionIdentityAsync(token);
+      if(string.IsNullOrWhiteSpace(identity.PrincipalId) || identity.TenantId != "printing-native-dev" || identity.DeviceId is not null)
+      { throw new InvalidOperationException("The native subject did not receive the intended server-derived identity."); }
+      Checks.Add("real-provider-login");
+      _stage = "wrong-origin-cookie";
+      await AssertWrongOriginAsync(origin, first.ExportCredential(), token);
+      await first.GetSessionIdentityAsync(token);
+      Checks.Add("wrong-origin-cookie-denied");
+
+      _stage = "permission-denied-user";
+      using(var denied = Session(origin))
+      {
+         await LoginAsync(denied, receiver, input, providerOrigin, callback, authorized: false, token);
+         await ExpectFailureAsync(() => denied.GetSessionIdentityAsync(token), QqqSessionException.FailureKind.PermissionDenied);
+         await denied.SignOutAsync(token);
+      }
+      Checks.Add("permission-denied-user");
+
+      _stage = "logout-replay";
+      QqqSessionCredential retired = first.ExportCredential();
+      await first.SignOutAsync(token);
+      using(var replay = Session(origin))
+      { await ExpectFailureAsync(() => replay.RestoreSessionAsync(retired, token), QqqSessionException.FailureKind.AuthenticationRequired); }
+      Checks.Add("logout-replay-denied");
+
+      _stage = "fresh-login-for-renewal";
+      using var renewable = Session(origin);
+      await LoginAsync(renewable, receiver, input, providerOrigin, callback, authorized: true, token);
+      QqqSessionBinding before = await renewable.GetSessionIdentityAsync(token);
+      HashSet<string> previousGrants = await provider.AccessGrantIdsAsync(token);
+      _stage = "server-refresh-after-expiry";
+      await Task.Delay(TimeSpan.FromSeconds(22), token);
+      await renewable.ResumeSessionAsync(token);
+      QqqSessionBinding after = await renewable.GetSessionIdentityAsync(token);
+      HashSet<string> refreshedGrants = await provider.AccessGrantIdsAsync(token);
+      if(before != after || !refreshedGrants.Except(previousGrants, StringComparer.Ordinal).Any())
+      { throw new InvalidOperationException("Renewal did not preserve the identity and obtain a new actual provider grant."); }
+      Checks.Add("server-refresh-after-expiry");
+
+      _stage = "provider-revocation-after-expiry";
+      await provider.RevokeRefreshGrantsAsync(token);
+      await Task.Delay(TimeSpan.FromSeconds(22), token);
+      await ExpectFailureAsync(() => renewable.ResumeSessionAsync(token), QqqSessionException.FailureKind.AuthenticationRequired);
+      Checks.Add("provider-revocation-denied");
+      _stage = "complete";
+   }
+
+   private static async Task LoginAsync(QqqSessionClient client, CallbackReceiver receiver, JsonObject input,
+      Uri providerOrigin, Uri callback, bool authorized, CancellationToken token)
+   {
+      string role = authorized ? "authorized" : "denied";
+      _stage = role + "-begin-pkce";
+      QqqBrowserLogin attempt = await client.BeginBrowserLoginAsync(callback, token);
+      _stage = role + "-generated-authorization-request";
+      Dictionary<string, string> parameters = attempt.AuthorizationUri.Query.TrimStart('?').Split('&')
+         .Select(entry => entry.Split('=', 2)).ToDictionary(pair => Uri.UnescapeDataString(pair[0]), pair => Uri.UnescapeDataString(pair[1]), StringComparer.Ordinal);
+      _authorizationRequestMatches = attempt.AuthorizationUri.AbsolutePath == "/application/o/authorize/"
+         && parameters.GetValueOrDefault("client_id") == ProviderSetup.Text(input, "clientId")
+         && parameters.GetValueOrDefault("redirect_uri") == callback.AbsoluteUri
+         && parameters.GetValueOrDefault("response_type") == "code"
+         && parameters.GetValueOrDefault("code_challenge_method") == "S256"
+         && parameters.GetValueOrDefault("state")?.Length == 43;
+      if(_authorizationRequestMatches != true)
+      { throw new InvalidOperationException("The generated authorization request differs from the exact provider registration."); }
+      _stage = role + "-provider-flow";
+      await ProviderFlow.AuthenticateAsync(attempt.AuthorizationUri, providerOrigin, callback,
+         ProviderSetup.Text(input, role + "Username"), ProviderSetup.Text(input, role + "Password"), token);
+      _stage = role + "-callback";
+      Uri actualCallback = await receiver.ReadAsync(token);
+      _stage = role + "-exchange";
+      await client.CompleteBrowserLoginAsync(attempt, actualCallback, token);
+   }
+
+   private static async Task ExpectFailureAsync(Func<Task> operation, QqqSessionException.FailureKind expected)
+   {
+      try { await operation(); }
+      catch(QqqSessionException exception) when(exception.Failure == expected) { return; }
+      throw new InvalidOperationException("The expected native authentication or permission denial did not occur.");
+   }
+
+   private static async Task AssertWrongOriginAsync(Uri origin, QqqSessionCredential credential, CancellationToken token)
+   {
+      using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseProxy = false })
+      { Timeout = TimeSpan.FromSeconds(15), MaxResponseContentBufferSize = 65536 };
+      using var request = new HttpRequestMessage(HttpMethod.Get, new Uri(origin, "/qqq/v1/qbit/printing/session"));
+      request.Headers.Add("X-QQQ-Client", QqqSessionClient.ClientChannel);
+      request.Headers.Add("Cookie", "sessionUUID=" + credential.SessionToken);
+      request.Headers.Add("Origin", "https://wrong-origin.invalid");
+      using HttpResponseMessage response = await http.SendAsync(request, token);
+      if(response.StatusCode != HttpStatusCode.Forbidden)
+      { throw new InvalidOperationException("The fixture did not reject a wrong-Origin cookie request."); }
+   }
+
+   private static async Task WaitForQqqAsync(Uri origin, CancellationToken token)
+   {
+      using var http = new FixtureHttp(origin);
+      for(int attempt = 0; attempt < 45; attempt++)
+      {
+         try
+         {
+            FixtureHttp.Reply response = await http.SendAsync("GET", "/qqq/v1/version", null, token);
+            if(response.Status == HttpStatusCode.OK && response.Json is not null) { return; }
+         }
+         catch(HttpRequestException) { }
+         await Task.Delay(TimeSpan.FromSeconds(2), token);
+      }
+      throw new InvalidOperationException("The owned native host did not become ready.");
+   }
+
+   private static Task WriteResultAsync(JsonObject? input, string status, string? failureType, string? sessionFailure)
+      => File.WriteAllTextAsync(ResultPath, JsonSerializer.Serialize(new
+      {
+         status, scope = "DEVELOPMENT_ONLY_UNRELEASED", coreSource = CoreSource, clientSource = ClientSource,
+         project = input?["project"]?.ToString(), observedUtc = DateTimeOffset.UtcNow, stage = _stage, failureType,
+         sessionFailure, lastRequestKind = FixtureHttp.LastRequestKind, lastHttpStatus = FixtureHttp.LastStatus,
+         lastProviderComponent = ProviderFlow.LastComponent,
+         authorizationRequestMatches = _authorizationRequestMatches,
+         requestClassifications = FixtureHttp.Trace,
+         providerLookupKind = ProviderSetup.LastLookupKind, providerLookupCount = ProviderSetup.LastLookupCount,
+         providerReadinessCounts = ProviderSetup.ReadinessCounts,
+         checks = Checks, installedUiAcceptance = false, providerRefreshTokensInClient = false,
+      }, new JsonSerializerOptions { WriteIndented = true }));
+}

dev/native-auth/client/ProviderFlow.cs

@@ -0,0 +1,95 @@
+// Copyright 2026 Kingsrook, LLC
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Net;
+using System.Text.Json.Nodes;
+
+namespace Printing.NativeAuth;
+
+/// <summary>Uses Authentik's real synthetic-user login stages; never fabricates a session or code.</summary>
+internal static class ProviderFlow
+{
+   internal static string? LastComponent { get; private set; }
+   internal static async Task AuthenticateAsync(Uri authorization, Uri origin, Uri callback, string username, string password, CancellationToken token)
+   {
+      using var browser = new FixtureHttp(origin, cookies: true);
+      using var callbackHttp = new FixtureHttp(new Uri(callback.GetLeftPart(UriPartial.Authority)));
+      Uri next = authorization;
+      for(int hop = 0; hop < 24; hop++)
+      {
+         if(next.GetLeftPart(UriPartial.Authority) == callback.GetLeftPart(UriPartial.Authority))
+         {
+            if(next.AbsolutePath != callback.AbsolutePath) { throw new InvalidOperationException("Unexpected callback path."); }
+            FixtureHttp.Reply result = await callbackHttp.SendAsync("GET", next, null, token);
+            if(result.Status != HttpStatusCode.OK) { throw new InvalidOperationException("The HTTPS callback receiver refused the provider redirect."); }
+            return;
+         }
+         if(next.GetLeftPart(UriPartial.Authority) != origin.GetLeftPart(UriPartial.Authority))
+         { throw new InvalidOperationException("A provider redirect left the fixture."); }
+         FixtureHttp.Reply page = await browser.SendAsync("GET", next, null, token);
+         if(page.Status is HttpStatusCode.Redirect or HttpStatusCode.SeeOther or HttpStatusCode.TemporaryRedirect)
+         {
+            next = new Uri(next, page.Location ?? throw new InvalidOperationException("Missing provider redirect."));
+            continue;
+         }
+         if(page.Status != HttpStatusCode.OK || !next.AbsolutePath.StartsWith("/if/flow/", StringComparison.Ordinal))
+         { throw new InvalidOperationException("Unexpected provider login navigation."); }
+         string slug = next.AbsolutePath["/if/flow/".Length..].Trim('/');
+         if(slug.Length == 0 || slug.Any(character => !char.IsAsciiLetterOrDigit(character) && character != '-'))
+         { throw new InvalidOperationException("Unexpected provider flow identifier."); }
+         var executor = new Uri(origin, "/api/v3/flows/executor/" + slug + "/?query=" + Uri.EscapeDataString(next.Query.TrimStart('?')));
+         JsonObject challenge = await ChallengeAsync(browser, executor, await browser.SendAsync("GET", executor, null, token), token);
+         bool redirected = false;
+         for(int stage = 0; stage < 10; stage++)
+         {
+            string component = ProviderSetup.Text(challenge, "component");
+            LastComponent = component switch
+            {
+               "ak-stage-identification" => "identification",
+               "ak-stage-password" => "password",
+               "ak-stage-consent" => "consent",
+               "xak-flow-redirect" => "redirect",
+               "ak-stage-access-denied" => "access-denied",
+               "ak-stage-flow-error" => "flow-error",
+               _ => "unsupported",
+            };
+            if(component == "xak-flow-redirect")
+            {
+               next = new Uri(origin, ProviderSetup.Text(challenge, "to"));
+               redirected = true;
+               break;
+            }
+            JsonObject response = component switch
+            {
+               "ak-stage-identification" => new JsonObject { ["component"] = component, ["uid_field"] = username },
+               "ak-stage-password" => new JsonObject { ["component"] = component, ["password"] = password },
+               "ak-stage-consent" => new JsonObject { ["component"] = component, ["consent"] = true },
+               _ => throw new InvalidOperationException("The provider requested an unsupported test login stage."),
+            };
+            challenge = await ChallengeAsync(browser, executor, await browser.SendAsync("POST", executor, response, token), token);
+            if(challenge["response_errors"] is JsonObject errors && errors.Count != 0)
+            { throw new InvalidOperationException("The real provider rejected the synthetic login response."); }
+         }
+         if(!redirected) { throw new InvalidOperationException("Provider stage bound exceeded."); }
+      }
+      throw new InvalidOperationException("Provider redirect bound exceeded.");
+   }
+
+   private static async Task<JsonObject> ChallengeAsync(FixtureHttp browser, Uri executor, FixtureHttp.Reply response, CancellationToken token)
+   {
+      // Authentik uses POST/redirect/GET when a real stage accepts its answer.
+      // Follow only that same HTTPS executor; other navigation uses typed flow redirects.
+      for(int redirect = 0; redirect < 8; redirect++)
+      {
+         if(response.Status == HttpStatusCode.OK) { return FixtureHttp.RequireJson(response, HttpStatusCode.OK); }
+         if(response.Status is not (HttpStatusCode.Redirect or HttpStatusCode.SeeOther) || response.Location is null)
+         { throw new InvalidOperationException("Unexpected provider stage response."); }
+         var location = new Uri(executor, response.Location);
+         if(location.GetLeftPart(UriPartial.Authority) != executor.GetLeftPart(UriPartial.Authority)
+            || location.AbsolutePath != executor.AbsolutePath)
+         { throw new InvalidOperationException("A stage redirect left its exact HTTPS executor."); }
+         response = await browser.SendAsync("GET", location, null, token);
+      }
+      throw new InvalidOperationException("Provider stage redirect bound exceeded.");
+   }
+}

dev/native-auth/client/ProviderSetup.cs

@@ -0,0 +1,184 @@
+// Copyright 2026 Kingsrook, LLC
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Net;
+using System.Text.Json.Nodes;
+
+namespace Printing.NativeAuth;
+
+/// <summary>Configures only the fresh project's synthetic provider and subjects.</summary>
+internal sealed class ProviderSetup : IDisposable
+{
+   internal static string? LastLookupKind { get; private set; }
+   internal static int? LastLookupCount { get; private set; }
+   internal static Dictionary<string, int> ReadinessCounts { get; } = new(StringComparer.Ordinal);
+   private readonly JsonObject _input;
+   private readonly FixtureHttp _admin;
+   private string _provider = "";
+   private string _authorizedUser = "";
+
+   internal ProviderSetup(JsonObject input)
+   {
+      _input = input;
+      _admin = new FixtureHttp(new Uri(Text(input, "providerOrigin")), adminToken: Text(input, "adminToken"));
+   }
+
+   internal static string Text(JsonObject document, string key) => document[key]?.ToString() ?? throw new InvalidOperationException("Required fixture field is absent.");
+
+   private async Task<JsonObject> ExactAsync(string path, CancellationToken token)
+   {
+      JsonObject page = FixtureHttp.RequireJson(await _admin.SendAsync("GET", path, null, token), HttpStatusCode.OK);
+      JsonArray records = page["results"]!.AsArray();
+      LastLookupKind = LookupKind(path);
+      LastLookupCount = records.Count;
+      if(records.Count != 1) { throw new InvalidOperationException("Required provider object is absent or ambiguous."); }
+      return records[0]!.AsObject();
+   }
+
+   private async Task<JsonObject> CreateAsync(string path, JsonObject body, CancellationToken token)
+      => FixtureHttp.RequireJson(await _admin.SendAsync("POST", path, body, token), HttpStatusCode.Created);
+
+   internal async Task WaitReadyAsync(CancellationToken token)
+   {
+      string[] paths = ["/api/v3/flows/instances/?slug=default-authentication-flow",
+         "/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent",
+         "/api/v3/flows/instances/?slug=default-provider-invalidation-flow",
+         "/api/v3/propertymappings/provider/scope/?scope_name=openid",
+         "/api/v3/propertymappings/provider/scope/?scope_name=profile",
+         "/api/v3/propertymappings/provider/scope/?scope_name=email",
+         "/api/v3/propertymappings/provider/scope/?scope_name=offline_access"];
+      for(int attempt = 0; attempt < 60; attempt++)
+      {
+         bool ready = true;
+         try
+         {
+            foreach(string path in paths)
+            {
+               FixtureHttp.Reply reply = await _admin.SendAsync("GET", path, null, token);
+               JsonArray? records = reply.Status == HttpStatusCode.OK ? reply.Json?["results"] as JsonArray : null;
+               string kind = LookupKind(path);
+               ReadinessCounts[kind] = records?.Count ?? -1;
+               if(records?.Count > 1) { throw new InvalidOperationException("An owned provider bootstrap dependency is ambiguous."); }
+               bool present = records is { Count: 1 };
+               if(kind == "authentication-flow")
+               { present &= records is { Count: 1 } && records[0]?["stages"] is JsonArray { Count: >= 4 }; }
+               ready &= present;
+            }
+            if(ready) { return; }
+         }
+         catch(HttpRequestException) { }
+         await Task.Delay(TimeSpan.FromSeconds(2), token);
+      }
+      throw new InvalidOperationException("The owned provider bootstrap did not become ready.");
+   }
+
+   private static string LookupKind(string path) => path switch
+   {
+      "/api/v3/flows/instances/?slug=default-authentication-flow" => "authentication-flow",
+      "/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent" => "authorization-flow",
+      "/api/v3/flows/instances/?slug=default-provider-invalidation-flow" => "invalidation-flow",
+      "/api/v3/propertymappings/provider/scope/?scope_name=openid" => "scope-openid",
+      "/api/v3/propertymappings/provider/scope/?scope_name=profile" => "scope-profile",
+      "/api/v3/propertymappings/provider/scope/?scope_name=email" => "scope-email",
+      "/api/v3/propertymappings/provider/scope/?scope_name=offline_access" => "scope-offline-access",
+      _ => "other",
+   };
+
+   internal async Task ConfigureAsync(CancellationToken token)
+   {
+      JsonObject authentication = await ExactAsync("/api/v3/flows/instances/?slug=default-authentication-flow", token);
+      JsonObject authorization = await ExactAsync("/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent", token);
+      JsonObject invalidation = await ExactAsync("/api/v3/flows/instances/?slug=default-provider-invalidation-flow", token);
+      var mappings = new JsonArray();
+      foreach(string scope in new[] { "openid", "profile", "email", "offline_access" })
+      {
+         mappings.Add((await ExactAsync("/api/v3/propertymappings/provider/scope/?scope_name=" + scope, token))["pk"]!.DeepClone());
+      }
+      JsonObject groupsMapping = await CreateAsync("/api/v3/propertymappings/provider/scope/", new JsonObject
+      {
+         ["name"] = Text(_input, "project") + "-groups",
+         ["scope_name"] = "profile",
+         ["expression"] = "return {\"groups\": [group.name for group in user.ak_groups.all()]}",
+      }, token);
+      mappings.Add(groupsMapping["pk"]!.DeepClone());
+      JsonObject group = await CreateAsync("/api/v3/core/groups/", new JsonObject { ["name"] = "printing_admin", ["is_superuser"] = false }, token);
+      JsonObject user = await CreateUserAsync("authorizedUsername", "authorizedPassword", new JsonArray(group["pk"]!.DeepClone()), token);
+      _authorizedUser = Text(user, "pk");
+      await CreateUserAsync("deniedUsername", "deniedPassword", new JsonArray(), token);
+      JsonObject provider = await CreateAsync("/api/v3/providers/oauth2/", new JsonObject
+      {
+         ["name"] = Text(_input, "project"),
+         ["authentication_flow"] = authentication["pk"]!.DeepClone(),
+         ["authorization_flow"] = authorization["pk"]!.DeepClone(),
+         ["invalidation_flow"] = invalidation["pk"]!.DeepClone(),
+         ["client_type"] = "confidential",
+         ["grant_types"] = new JsonArray("authorization_code", "refresh_token"),
+         ["client_id"] = Text(_input, "clientId"),
+         ["client_secret"] = Text(_input, "clientSecret"),
+         ["access_code_validity"] = "minutes=1",
+         ["access_token_validity"] = "seconds=20",
+         ["refresh_token_validity"] = "minutes=5",
+         ["refresh_token_threshold"] = "minutes=4",
+         ["redirect_uris"] = new JsonArray(new JsonObject { ["matching_mode"] = "strict", ["url"] = Text(_input, "callback") }),
+         ["property_mappings"] = mappings,
+         ["issuer_mode"] = "per_provider",
+         ["include_claims_in_id_token"] = true,
+      }, token);
+      _provider = Text(provider, "pk");
+      if(Text(provider, "client_id") != Text(_input, "clientId")
+         || Text(provider, "authentication_flow") != Text(authentication, "pk"))
+      { throw new InvalidOperationException("The real provider did not retain the configured client identifier."); }
+      JsonObject application = await CreateAsync("/api/v3/core/applications/", new JsonObject
+      {
+         ["name"] = Text(_input, "project"), ["slug"] = Text(_input, "project"),
+         ["provider"] = provider["pk"]!.DeepClone(), ["policy_engine_mode"] = "all",
+      }, token);
+      if(Text(application, "provider") != _provider)
+      { throw new InvalidOperationException("The real provider application binding differs from the configured provider."); }
+   }
+
+   private async Task<JsonObject> CreateUserAsync(string usernameKey, string passwordKey, JsonArray groups, CancellationToken token)
+   {
+      JsonObject user = await CreateAsync("/api/v3/core/users/", new JsonObject
+      {
+         ["username"] = Text(_input, usernameKey), ["name"] = "Synthetic native qualification subject",
+         ["email"] = Text(_input, usernameKey) + "@example.invalid", ["is_active"] = true,
+         ["type"] = "internal", ["groups"] = groups,
+      }, token);
+      FixtureHttp.Reply response = await _admin.SendAsync("POST", "/api/v3/core/users/" + Text(user, "pk") + "/set_password/",
+         new JsonObject { ["password"] = Text(_input, passwordKey) }, token);
+      if(response.Status != HttpStatusCode.NoContent) { throw new InvalidOperationException("Synthetic account password configuration failed."); }
+      return user;
+   }
+
+   private async Task<JsonArray> GrantsAsync(string kind, CancellationToken token)
+   {
+      JsonObject page = FixtureHttp.RequireJson(await _admin.SendAsync("GET", "/api/v3/oauth2/" + kind + "/?provider=" + _provider + "&user=" + _authorizedUser, null, token), HttpStatusCode.OK);
+      JsonArray records = page["results"]!.AsArray();
+      if(records.Count is 0 or > 20) { throw new InvalidOperationException("The synthetic provider grant set is missing or unexpectedly large."); }
+      foreach(JsonNode? node in records)
+      {
+         JsonObject record = node!.AsObject();
+         string provider = record["provider"] is JsonObject nested ? Text(nested, "pk") : Text(record, "provider");
+         if(provider != _provider || Text(record["user"]!.AsObject(), "pk") != _authorizedUser)
+         { throw new InvalidOperationException("The provider grant escaped the synthetic subject scope."); }
+      }
+      return records;
+   }
+
+   internal async Task<HashSet<string>> AccessGrantIdsAsync(CancellationToken token)
+      => (await GrantsAsync("access_tokens", token)).Select(node => Text(node!.AsObject(), "pk")).ToHashSet(StringComparer.Ordinal);
+
+   internal async Task RevokeRefreshGrantsAsync(CancellationToken token)
+   {
+      foreach(JsonNode? node in await GrantsAsync("refresh_tokens", token))
+      {
+         string id = Text(node!.AsObject(), "pk");
+         if(!Guid.TryParse(id, out _) && !long.TryParse(id, out _)) { throw new InvalidOperationException("Unexpected provider grant identifier."); }
+         FixtureHttp.Reply response = await _admin.SendAsync("DELETE", "/api/v3/oauth2/refresh_tokens/" + id + "/", null, token);
+         if(response.Status != HttpStatusCode.NoContent) { throw new InvalidOperationException("Synthetic provider revocation failed."); }
+      }
+   }
+
+   public void Dispose() => _admin.Dispose();
+}

dev/native-auth/copy-root.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+set -eu
+attempt=0
+while [ ! -s /data/caddy/pki/authorities/local/root.crt ]; do
+   attempt=$((attempt + 1))
+   if [ "$attempt" -ge 60 ]; then
+      echo 'The fixture public CA certificate did not become ready.' >&2
+      exit 1
+   fi
+   sleep 1
+done
+# Never copy the key or mount the private CA volume into a client/server.
+cp /data/caddy/pki/authorities/local/root.crt /trust/root.crt
+chmod 0644 /trust/root.crt

dev/native-auth/java/NativeAuthHost.java

@@ -0,0 +1,224 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// SPDX-License-Identifier: Apache-2.0
+package com.kingsrook.qbits.printing;
+
+import java.net.URI;
+import java.sql.Connection;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.instances.AbstractQQQApplication;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.authentication.AuthScope;
+import com.kingsrook.qqq.backend.core.model.metadata.authentication.OAuth2AuthenticationMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.authentication.OAuth2NativeSessionLoginMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.branding.QBrandingMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleCustomizerInterface;
+import com.kingsrook.qqq.backend.core.modules.authentication.implementations.metadata.RedirectStateMetaDataProducer;
+import com.kingsrook.qqq.backend.core.modules.authentication.implementations.metadata.UserSessionMetaDataProducer;
+import com.kingsrook.qqq.backend.core.modules.authentication.implementations.metadata.UserSessionRefreshTokenMetaDataProducer;
+import com.kingsrook.qqq.backend.core.modules.authentication.implementations.model.UserSession;
+import com.kingsrook.qqq.backend.core.modules.authentication.implementations.model.UserSessionRefreshToken;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSTableBackendDetails;
+import com.kingsrook.qqq.middleware.javalin.QApplicationJavalinServer;
+import com.kingsrook.qqq.middleware.javalin.QApplicationLauncher;
+import com.kingsrook.qqq.middleware.javalin.QApplicationLauncherConfig;
+import io.javalin.http.Context;
+import io.javalin.http.ForbiddenResponse;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+/**
+ * Opt-in container fixture for the pinned upstream native-session candidate.
+ * Standard OAuth2 code exchange, session storage and encrypted renewal are used
+ * unchanged. No installed pairing, password authentication double or printer.
+ */
+public final class NativeAuthHost extends AbstractQQQApplication
+{
+   private static final String TENANT = "printing-native-dev";
+   private final String backendName = "printing-native-auth-" + UUID.randomUUID();
+   private final String jdbcUrl = "jdbc:h2:file:/data/printing-native-auth";
+   private final String databasePassword = required("NATIVE_QQQ_DATABASE_PASSWORD");
+   private final URI origin = httpsOrigin(required("NATIVE_QQQ_ORIGIN"));
+   private final int port = Integer.parseInt(required("NATIVE_QQQ_PORT"));
+   private final DriverDataSource source = new DriverDataSource(jdbcUrl, "sa", databasePassword);
+   private final PrintingService service = new PrintingService(source, TENANT);
+
+   private NativeAuthHost() throws Exception
+   {
+      if(port < 1024 || port > 65535)
+      {
+         throw new IllegalArgumentException("Unsupported internal fixture port");
+      }
+      service.initialize();
+      try(Connection connection = source.getConnection(); var statement = connection.createStatement())
+      {
+         statement.execute("CREATE TABLE IF NOT EXISTS userSession (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, uuid VARCHAR(40) NOT NULL UNIQUE, userId VARCHAR(100), accessToken CLOB, createDate TIMESTAMP WITH TIME ZONE, modifyDate TIMESTAMP WITH TIME ZONE)");
+         statement.execute("CREATE TABLE IF NOT EXISTS redirectState (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, state VARCHAR(45) NOT NULL UNIQUE, redirectUri VARCHAR(4096), createDate TIMESTAMP WITH TIME ZONE)");
+         statement.execute("CREATE TABLE IF NOT EXISTS userSessionRefreshToken (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, sessionUuid VARCHAR(40) NOT NULL UNIQUE, refreshToken CLOB, refreshTokenExpiresAt TIMESTAMP WITH TIME ZONE, sessionStartedAt TIMESTAMP WITH TIME ZONE, createDate TIMESTAMP WITH TIME ZONE, modifyDate TIMESTAMP WITH TIME ZONE)");
+      }
+   }
+
+   public static void main(String[] args) throws Exception
+   {
+      NativeAuthHost host = new NativeAuthHost();
+      QApplicationLauncher.run(host, new QApplicationLauncherConfig()
+         .withServerCustomizer(host::configure));
+   }
+
+   @Override
+   public QInstance defineQInstance() throws QException
+   {
+      QInstance instance = new QInstance();
+      instance.setFailOnMetaDataProducerError(true);
+      instance.setHomeAppName("printing");
+      instance.setBranding(new QBrandingMetaData().withAppName("QQQ native authentication fixture"));
+      instance.addBackend(new RDBMSBackendMetaData().withName(backendName).withVendor("h2").withHostName("fixture")
+         .withDatabaseName("printing-native-auth").withUsername("sa").withPassword(databasePassword).withJdbcUrl(jdbcUrl));
+      instance.addTable(new UserSessionMetaDataProducer(backendName).produce(instance));
+      instance.addTable(new RedirectStateMetaDataProducer(backendName).produce(instance));
+      instance.addTable(new UserSessionRefreshTokenMetaDataProducer(backendName).produce(instance));
+
+      String issuer = required("NATIVE_AUTH_ISSUER");
+      URI issuerUri = URI.create(issuer);
+      if(!"https".equals(issuerUri.getScheme()) || issuerUri.getHost() == null
+         || issuerUri.getRawUserInfo() != null || issuerUri.getRawQuery() != null || issuerUri.getRawFragment() != null || !issuer.endsWith("/"))
+      {
+         throw new IllegalArgumentException("An explicit HTTPS fixture issuer ending in slash is required");
+      }
+      OAuth2AuthenticationMetaData authentication = new OAuth2AuthenticationMetaData()
+         .withBaseUrl(issuer).withExternalBaseUrl(issuer)
+         .withClientId(required("NATIVE_AUTH_CLIENT_ID")).withClientSecret(required("NATIVE_AUTH_CLIENT_SECRET"))
+         .withScopes("openid profile email offline_access")
+         .withUserSessionTableName(UserSession.TABLE_NAME).withRedirectStateTableName(RedirectStateMetaDataProducer.TABLE_NAME)
+         .withRefreshTokenTableName(UserSessionRefreshToken.TABLE_NAME)
+         .withRefreshTokensEnabled(true).withRefreshTokenSkewSeconds(0).withMaxSessionLifetimeSeconds(3600)
+         .withRefreshTokenEncryptionKey(required("NATIVE_QQQ_REFRESH_KEY")).withRefreshTokenEncryptionKeyId("fixture-1")
+         .withNativeSessionLogin(new OAuth2NativeSessionLoginMetaData().withIssuer(issuer)
+            .withDiscoveryUrl(issuer + ".well-known/openid-configuration")
+            .withRedirectUris(List.of(required("NATIVE_AUTH_REDIRECT_URI"))));
+      authentication.withName("printing-native-provider").withSessionStoreEnabled(false)
+         .withCustomizer(new QCodeReference(PrintingPermissions.class));
+      instance.registerAuthenticationProvider(AuthScope.instanceDefault(), authentication);
+      new PrintingQBitProducer().withConfig(new PrintingQBitConfig().withBackendName(backendName).withService(service))
+         .produce(instance, "printing");
+      for(QTableMetaData table : instance.getTables().values())
+      {
+         if(backendName.equals(table.getBackendName()))
+         {
+            table.withBackendDetails(new RDBMSTableBackendDetails().withTableName(table.getName().toUpperCase(Locale.ROOT)));
+            for(var field : table.getFields().values())
+            {
+               field.withBackendName(field.getName().toUpperCase(Locale.ROOT));
+            }
+         }
+      }
+      return instance;
+   }
+
+   private void configure(QApplicationJavalinServer server)
+   {
+      // Only the owned TLS proxy is published; this HTTP listener remains inside
+      // the Compose network. Forwarded HTTPS is required even for discovery.
+      server.withPort(port).withServeFrontendNext(false).withServeFrontendMaterialDashboard(false)
+         .withAdditionalRouteProviders(List.of(new PrintingRealtimeRoutes(service)))
+         .withJavalinConfigCustomizer(config ->
+         {
+            config.jetty.host = "0.0.0.0";
+            config.http.maxRequestSize = 1048576;
+            config.routes.before(this::guardOrigin);
+         });
+   }
+
+   private void guardOrigin(Context context)
+   {
+      if(!origin.getRawAuthority().equalsIgnoreCase(context.header("Host"))
+         || !"https".equals(context.header("X-Forwarded-Proto")))
+      {
+         throw new ForbiddenResponse("The fixture requires its configured HTTPS proxy origin");
+      }
+      String suppliedOrigin = context.header("Origin");
+      if(suppliedOrigin != null && !origin.toString().equals(suppliedOrigin))
+      {
+         throw new ForbiddenResponse("Cross-origin fixture requests are not allowed");
+      }
+      if("cross-site".equalsIgnoreCase(context.header("Sec-Fetch-Site"))
+         || context.header("X-QQQ-In-Process-Session") != null)
+      {
+         throw new ForbiddenResponse("Only standard native session authentication is allowed");
+      }
+      boolean unsafe = !Set.of("GET", "HEAD", "OPTIONS").contains(context.method().name());
+      boolean cookie = context.cookie("sessionUUID") != null || context.cookie("sessionId") != null;
+      if(unsafe && cookie && suppliedOrigin == null)
+      {
+         throw new ForbiddenResponse("Cookie mutations require the configured Origin");
+      }
+   }
+
+   /** Only maps claims after the unchanged standard OAuth2 module authenticates. */
+   public static final class PrintingPermissions implements QAuthenticationModuleCustomizerInterface
+   {
+      @Override
+      public void customizeSession(QInstance instance, QSession session, Map<String, Object> context)
+      {
+         session.setPermissions(Set.of());
+         session.withSecurityKeyValue("printing_tenant", TENANT);
+         Object claims = context.get("jwtPayloadJsonObject");
+         if(session.getUser() != null && claims instanceof JSONObject payload)
+         {
+            JSONArray groups = payload.optJSONArray("groups");
+            if(groups != null && groups.toList().contains("printing_admin"))
+            {
+               session.setPermissions(Set.of("printing_admin"));
+            }
+         }
+      }
+   }
+
+   private static URI httpsOrigin(String value)
+   {
+      URI parsed = URI.create(value);
+      if(!"https".equals(parsed.getScheme()) || parsed.getHost() == null || parsed.getRawUserInfo() != null
+         || parsed.getRawQuery() != null || parsed.getRawFragment() != null || !parsed.getRawPath().isEmpty())
+      {
+         throw new IllegalArgumentException("A root HTTPS fixture origin without trailing slash is required");
+      }
+      return parsed;
+   }
+
+   private static String required(String name)
+   {
+      String value = System.getenv(name);
+      if(value == null || value.isBlank())
+      {
+         throw new IllegalArgumentException("Set the synthetic fixture variable " + name);
+      }
+      return value;
+   }
+}

dev/native-auth/start-client.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+set -eu
+# This first request must fail with the ordinary TLS validator, before trust.
+dotnet /app/NativeAuth.dll assert-untrusted
+test -s /trust/root.crt
+cp /trust/root.crt /usr/local/share/ca-certificates/printing-native-fixture.crt
+update-ca-certificates >/dev/null 2>&1
+exec dotnet /app/NativeAuth.dll test

dev/native-auth/start-server.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+set -eu
+# Only this disposable container's JRE trust store is changed. The mounted file
+# is the public root certificate; the CA private key is never mounted here.
+test -s /trust/root.crt
+keytool -importcert -noprompt -alias printing-native-fixture -file /trust/root.crt -cacerts -storepass changeit >/dev/null 2>&1
+exec java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' com.kingsrook.qbits.printing.NativeAuthHost

dev/run-tests.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+set -eu
+case "$TEST_RUN" in run-[a-f0-9]*) ;; *) echo 'Invalid owned test run' >&2; exit 2;; esac
+mkdir -p "/work/$TEST_RUN/s3"
+java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' com.kingsrook.qbits.printing.DevHost --wait-storage
+java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' S3PrintingQualification "/work/$TEST_RUN/s3" http://127.0.0.1:9000 "$TEST_RUN"
+exec java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' com.kingsrook.qbits.printing.WorkloadFixture "/work/$TEST_RUN" "$WORKLOAD_MODE"

dev/tests/Authentik.Tests.ps1

@@ -0,0 +1,71 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+# No Docker or HTTP calls: these regressions exercise private bootstrap state.
+BeforeAll {
+   $script:authScript = Join-Path $PSScriptRoot '../Invoke-Authentik.ps1'
+   $script:project = 'qbit-printing-dev-0123456789abcdef0123456789abcdef'
+}
+
+Describe 'Authentik development bootstrap' {
+   BeforeEach {
+      $state = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N'))
+      New-Item -ItemType Directory -Path $state | Out-Null
+      $envFile = Join-Path $state 'compose.env'
+      $prefix = "PRINTING_DEV_PROJECT=$project`nMINIO_ROOT_USER=synthetic`nQQQ_HTTP_PORT=19081`n"
+      [IO.File]::WriteAllText($envFile, $prefix)
+   }
+
+   It 'preserves common environment values and creates a matching hashed admin password without console output' {
+      $output = @(& $authScript -Action Initialize -StateDirectory $state -ProjectName $project)
+      $output.Count | Should -Be 0
+      $environment = Get-Content -LiteralPath $envFile -Raw
+      $environment.StartsWith($prefix, [StringComparison]::Ordinal) | Should -BeTrue
+      [regex]::Matches($environment, '(?m)^AUTHENTIK_[A-Z_]+=').Count | Should -Be 5
+      $private = Get-Content -LiteralPath (Join-Path $state 'auth-secrets.json') -Raw | ConvertFrom-Json
+      $match = [regex]::Match($environment, '(?m)^AUTHENTIK_BOOTSTRAP_PASSWORD_HASH=''pbkdf2_sha256\$1000000\$([^$]+)\$([^'']+)''')
+      $match.Success | Should -BeTrue
+      $actual = [Convert]::ToBase64String([Security.Cryptography.Rfc2898DeriveBytes]::Pbkdf2($private.adminPassword, [Text.Encoding]::UTF8.GetBytes($match.Groups[1].Value), 1000000, [Security.Cryptography.HashAlgorithmName]::SHA256, 32))
+      [string]::Equals($actual, $match.Groups[2].Value, [StringComparison]::Ordinal) | Should -BeTrue
+   }
+
+   It 'does not rotate credentials or append duplicate keys on repeated initialization' {
+      & $authScript -Action Initialize -StateDirectory $state -ProjectName $project
+      $beforeEnvironment = (Get-FileHash -LiteralPath $envFile).Hash
+      $beforeSecrets = (Get-FileHash -LiteralPath (Join-Path $state 'auth-secrets.json')).Hash
+      & $authScript -Action Initialize -StateDirectory $state -ProjectName $project
+      (Get-FileHash -LiteralPath $envFile).Hash | Should -Be $beforeEnvironment
+      (Get-FileHash -LiteralPath (Join-Path $state 'auth-secrets.json')).Hash | Should -Be $beforeSecrets
+   }
+
+   It 'rejects a changed project or port without overwriting private state' {
+      & $authScript -Action Initialize -StateDirectory $state -ProjectName $project
+      $before = (Get-FileHash -LiteralPath $envFile).Hash
+      { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project -Port 19011 } | Should -Throw '*different project or port*'
+      { & $authScript -Action Initialize -StateDirectory $state -ProjectName 'qbit-printing-dev-aaaaaaaa' } | Should -Throw '*different project or port*'
+      (Get-FileHash -LiteralPath $envFile).Hash | Should -Be $before
+   }
+
+   It 'rejects partial initialization rather than assigning different secrets to an existing database' {
+      Add-Content -LiteralPath $envFile -Value 'AUTHENTIK_SECRET_KEY=synthetic'
+      { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*Partial Authentik initialization*'
+      Test-Path -LiteralPath (Join-Path $state 'auth-secrets.json') | Should -BeFalse
+   }
+
+   It 'rejects missing environment keys after initialization' {
+      & $authScript -Action Initialize -StateDirectory $state -ProjectName $project
+      [IO.File]::WriteAllText($envFile, $prefix)
+      { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*incomplete or ambiguous*'
+   }
+
+   It 'withholds malformed private configuration contents' {
+      [IO.File]::WriteAllText((Join-Path $state 'auth-secrets.json'), '{"private":"synthetic-value-to-withhold"')
+      { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*contents are withheld*'
+   }
+
+   It 'refuses a state directory inside the source checkout before writing' {
+      $repository = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '../..'))
+      { & $authScript -Action Initialize -StateDirectory $repository -ProjectName $project } | Should -Throw '*outside the source checkout*'
+   }
+}

dev/tests/Lifecycle.Tests.ps1

@@ -0,0 +1,129 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+# Ownership regressions use mocked Docker metadata; no containers or network calls.
+BeforeAll {
+   $script:entrypoint = Join-Path $PSScriptRoot '../Invoke-Dev.ps1'
+   $tokens = $null
+   $errors = $null
+   $ast = [Management.Automation.Language.Parser]::ParseFile($entrypoint, [ref]$tokens, [ref]$errors)
+   if ($errors.Count)
+   {
+      throw 'Entrypoint parsing failed.'
+   }
+   foreach ($name in @('Assert-OwnedResource', 'Get-RecordedAuthentikPort'))
+   {
+      $guard = $ast.Find({ param($node) $node -is [Management.Automation.Language.FunctionDefinitionAst] -and $node.Name -eq $name }, $true)
+      . ([scriptblock]::Create($guard.Extent.Text))
+   }
+   $script:project = 'qbit-printing-dev-0123456789abcdef0123456789abcdef'
+   function docker
+   {
+      throw 'Unmocked Docker call refused.'
+   }
+}
+
+Describe 'Development lifecycle ownership' {
+   BeforeEach {
+      $script:wrongResource = ''
+      Mock docker {
+         $global:LASTEXITCODE = 0
+         $command = $args -join ' '
+         if ($command.StartsWith('ps -aq', [StringComparison]::Ordinal))
+         {
+            return 'container-id'
+         }
+         if ($command.StartsWith('network ls', [StringComparison]::Ordinal))
+         {
+            return 'network-id'
+         }
+         if ($command.StartsWith('volume ls', [StringComparison]::Ordinal))
+         {
+            return 'volume-id'
+         }
+         if ($script:wrongResource -and $command.Contains($script:wrongResource, [StringComparison]::Ordinal))
+         {
+            return 'another-project'
+         }
+         return $script:project
+      }
+   }
+   It 'accepts only consistently labeled containers, networks and volumes' {
+      { Assert-OwnedResource } | Should -Not -Throw
+      Should -Invoke docker -Times 6 -Exactly
+   }
+   It 'rejects a foreign container before any cleanup' {
+      $script:wrongResource = 'container-id'
+      { Assert-OwnedResource } | Should -Throw '*Container ownership mismatch*'
+      Should -Invoke docker -ParameterFilter { ($args -join ' ') -match 'down|remove|prune' } -Times 0
+   }
+   It 'rejects a foreign network before any cleanup' {
+      $script:wrongResource = 'network-id'
+      { Assert-OwnedResource } | Should -Throw '*Network ownership mismatch*'
+      Should -Invoke docker -ParameterFilter { ($args -join ' ') -match 'down|remove|prune' } -Times 0
+   }
+   It 'rejects a foreign volume before any cleanup' {
+      $script:wrongResource = 'volume-id'
+      { Assert-OwnedResource } | Should -Throw '*Volume ownership mismatch*'
+      Should -Invoke docker -ParameterFilter { ($args -join ' ') -match 'down|remove|prune' } -Times 0
+   }
+   It 'refuses an existing unowned state directory before contacting Docker' {
+      { & $entrypoint -Action Stop -StateDirectory $TestDrive } | Should -Throw '*lacks this tool ownership record*'
+      Should -Invoke docker -Times 0
+   }
+   It 'rejects persistent experimental startup before any state creation' {
+      $path = Join-Path $TestDrive 'experimental-start'
+      { & $entrypoint -Action Start -ExperimentalNativeAuth -StateDirectory $path } | Should -Throw '*Test-only profile*'
+      Test-Path -LiteralPath $path | Should -BeFalse
+      Should -Invoke docker -Times 0
+   }
+   It 'does not repurpose a saved standard environment for experimental authentication' {
+      $path = Join-Path $TestDrive 'standard-environment'
+      [IO.Directory]::CreateDirectory($path) | Out-Null
+      @{sourceRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '../..')); project = $project; authentik = $false } |
+         ConvertTo-Json | Set-Content (Join-Path $path 'owner.json')
+      { & $entrypoint -Action Test -ExperimentalNativeAuth -StateDirectory $path } | Should -Throw '*cannot be repurposed*'
+      Should -Invoke docker -Times 0
+   }
+   It 'refuses a forged project name before contacting Docker' {
+      $path = Join-Path $TestDrive 'forged'
+      [IO.Directory]::CreateDirectory($path) | Out-Null
+      @{sourceRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '../..')); project = 'unrelated'; authentik = $false } | ConvertTo-Json | Set-Content (Join-Path $path 'owner.json')
+      { & $entrypoint -Action Stop -StateDirectory $path } | Should -Throw '*State ownership mismatch*'
+      Should -Invoke docker -Times 0
+   }
+   It 'restores a nondefault Authentik port from saved state' {
+      $script:envFile = Join-Path $TestDrive 'ports.env'
+      [IO.File]::WriteAllText($envFile, "QQQ_HTTP_PORT=19081`nAUTHENTIK_HTTP_PORT=19011`n")
+      Get-RecordedAuthentikPort | Should -Be 19011
+   }
+   It 'rejects ambiguous saved port configuration' {
+      $script:envFile = Join-Path $TestDrive 'ambiguous.env'
+      [IO.File]::WriteAllText($envFile, "AUTHENTIK_HTTP_PORT=19010`nAUTHENTIK_HTTP_PORT=19011`n")
+      { Get-RecordedAuthentikPort } | Should -Throw '*missing or invalid*'
+   }
+   It 'rejects a state ancestor junction or symlink before writing or contacting Docker' {
+      $target = Join-Path $TestDrive 'target'
+      $link = Join-Path $TestDrive 'linked'
+      [IO.Directory]::CreateDirectory($target) | Out-Null
+      if ($IsWindows)
+      {
+         New-Item -ItemType Junction -Path $link -Target $target -ErrorAction Stop | Out-Null
+      }
+      else
+      {
+         New-Item -ItemType SymbolicLink -Path $link -Target $target -ErrorAction Stop | Out-Null
+      }
+      try
+      {
+         { & $entrypoint -Action Start -StateDirectory (Join-Path $link 'new-state') } | Should -Throw '*symbolic link or reparse point*'
+         Test-Path -LiteralPath (Join-Path $target 'new-state') | Should -BeFalse
+         Should -Invoke docker -Times 0
+      }
+      finally
+      {
+         [IO.Directory]::Delete($link)
+      }
+   }
+}

dev/tests/NativeAuth.Tests.ps1

@@ -0,0 +1,71 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+# No Docker, TLS, provider or QQQ calls; only private input and result validation.
+BeforeAll {
+   $script:nativeScript = Join-Path $PSScriptRoot '../Invoke-NativeAuth.ps1'
+   $script:project = 'qbit-printing-dev-0123456789abcdef0123456789abcdef'
+   $script:requiredChecks = @('untrusted-tls-refused', 'typed-native-grant', 'real-provider-login', 'wrong-origin-cookie-denied', 'permission-denied-user', 'logout-replay-denied', 'server-refresh-after-expiry', 'provider-revocation-denied')
+}
+
+Describe 'Experimental native provider qualification state' {
+   BeforeEach {
+      $state = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N'))
+      New-Item -ItemType Directory -Path $state | Out-Null
+      $envFile = Join-Path $state 'compose.env'
+      $prefix = "PRINTING_DEV_PROJECT=$project`nMINIO_ROOT_USER=synthetic`n"
+      [IO.File]::WriteAllText($envFile, $prefix)
+      @{ project = $project; clientId = $project; bootstrapToken = 'synthetic-admin'; clientSecret = 'synthetic-client'; userPassword = 'synthetic-user' } |
+         ConvertTo-Json | Set-Content -LiteralPath (Join-Path $state 'auth-secrets.json')
+      $script:report = @{
+         status = 'PASS'; scope = 'DEVELOPMENT_ONLY_UNRELEASED'; project = $project
+         coreSource = 'ecf0f550a0357cec6387c2b54efca128a405a629'
+         clientSource = '346fc285198908c47a2ee9db7b9adb53d5e88c3c'; checks = $requiredChecks
+      }
+      $script:resultFile = Join-Path $state 'native-auth-result.json'
+   }
+
+   It 'preserves common state and creates only the exact owned destinations without console secrets' {
+      $output = @(& $nativeScript -Action Initialize -StateDirectory $state -ProjectName $project)
+      $output.Count | Should -Be 0
+      (Get-Content -LiteralPath $envFile -Raw).StartsWith($prefix, [StringComparison]::Ordinal) | Should -BeTrue
+      $inputData = Get-Content -LiteralPath (Join-Path $state 'native-input.json') -Raw | ConvertFrom-Json
+      $inputData.qqqOrigin | Should -Be 'https://qqq.printing.internal'
+      $inputData.callback | Should -Be 'https://callback.printing.internal/oauth/callback'
+      $inputData.project | Should -Be $project
+      (Get-Content -LiteralPath $script:resultFile -Raw | ConvertFrom-Json).status | Should -Be 'NOT_RUN'
+      $before = (Get-FileHash -LiteralPath $envFile).Hash
+      { & $nativeScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*fresh owned environment*'
+      (Get-FileHash -LiteralPath $envFile).Hash | Should -Be $before
+   }
+
+   It 'refuses credentials owned by another project before writing native input' {
+      { & $nativeScript -Action Initialize -StateDirectory $state -ProjectName 'qbit-printing-dev-aaaaaaaa' } | Should -Throw '*does not match*'
+      Test-Path -LiteralPath (Join-Path $state 'native-input.json') | Should -BeFalse
+   }
+
+   It 'accepts the exact source and complete bounded report' {
+      $script:report | ConvertTo-Json | Set-Content -LiteralPath $script:resultFile
+      & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project | Should -Match 'candidate is unpublished'
+   }
+
+   It 'rejects a passing report from a different source' {
+      $script:report.coreSource = '0000000000000000000000000000000000000000'
+      $script:report | ConvertTo-Json | Set-Content -LiteralPath $script:resultFile
+      { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*exact source*'
+   }
+
+   It 'rejects missing renewal evidence instead of treating successful login as complete' {
+      $script:report.checks = @($requiredChecks | Where-Object { $_ -ne 'server-refresh-after-expiry' })
+      $script:report | ConvertTo-Json | Set-Content -LiteralPath $script:resultFile
+      { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*required checks*'
+   }
+
+   It 'rejects malformed or oversized reports without echoing their contents' {
+      [IO.File]::WriteAllText($script:resultFile, '{"private":"do-not-echo"')
+      { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*contents are withheld*'
+      [IO.File]::WriteAllText($script:resultFile, ('x' * 65537))
+      { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*bounded size*'
+   }
+}

dev/tests/ProviderDiagnostics.Tests.ps1

@@ -0,0 +1,51 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+BeforeAll {
+   $path = Join-Path $PSScriptRoot '../Invoke-Dev.ps1'
+   $tokens = $null
+   $errors = $null
+   $ast = [Management.Automation.Language.Parser]::ParseFile($path, [ref]$tokens, [ref]$errors)
+   if ($errors.Count) { throw 'Entrypoint parsing failed.' }
+   $function = $ast.Find({ param($node) $node -is [Management.Automation.Language.FunctionDefinitionAst] -and $node.Name -eq 'ConvertTo-ProviderErrorSummary' }, $true)
+   . ([scriptblock]::Create($function.Extent.Text))
+}
+
+Describe 'Private provider diagnostic redaction' {
+   It 'retains source coordinates but excludes exception values, locals and request data' {
+      $record = @{event = 'secret-request'; exception = @(@{exc_type = 'KeyError'; exc_value = 'secret-value'; frames = @(
+                  @{filename = '/authentik/flows/views/executor.py'; lineno = 42; name = 'post'; locals = @{password = 'secret-password'}; source = 'secret-source'},
+                  @{filename = '/outside/secret-path.py'; lineno = 3; name = 'unsafe'}
+               )
+            })
+      } | ConvertTo-Json -Depth 8 -Compress
+      $result = ConvertTo-ProviderErrorSummary @($record, 'secret-unstructured-line')
+      $result.exceptionTypes | Should -Be @('KeyError')
+      $result.frames.Count | Should -Be 1
+      $result.frames[0].function | Should -Be 'post'
+      $result | ConvertTo-Json -Depth 6 | Should -Not -Match 'secret|password|outside|locals|source'
+   }
+   It 'bounds frames and does not retain malformed or query-bearing coordinates' {
+      $frames = @(1..20 | ForEach-Object { @{filename = '/authentik/test.py'; lineno = $_; name = 'get'} })
+      $record = @{exception = @(@{exc_type = 'ValueError'; frames = $frames})} | ConvertTo-Json -Depth 8 -Compress
+      (ConvertTo-ProviderErrorSummary @($record)).frames.Count | Should -Be 12
+      $bad = @{exception = @(@{exc_type = 'secret?Error'; frames = @(@{filename = '/authentik/test.py?secret'; lineno = 1; name = 'get'})})} | ConvertTo-Json -Depth 8 -Compress
+      $result = ConvertTo-ProviderErrorSummary @($bad, '{broken', 'null')
+      $result.exceptionTypes.Count | Should -Be 0
+      $result.frames.Count | Should -Be 0
+   }
+   It 'records only fixed known warning flags from unstructured output' {
+      $result = ConvertTo-ProviderErrorSummary @('Invalid client identifier secret-query', 'Non-applicable authentication flow secret', 'failed to resolve application secret')
+      $result.warnings.invalidClientIdentifier | Should -BeTrue
+      $result.warnings.nonApplicableAuthenticationFlow | Should -BeTrue
+      $result.warnings.failedToResolveApplication | Should -BeTrue
+      $result | ConvertTo-Json -Depth 6 | Should -Not -Match 'secret'
+   }
+   It 'retains fixed DRF exception names without their messages' {
+      $record = @{exception = @(@{exc_type = 'PermissionDenied'; exc_value = 'secret-csrf-value'; frames = @()})} | ConvertTo-Json -Depth 5 -Compress
+      $result = ConvertTo-ProviderErrorSummary @($record)
+      $result.exceptionTypes | Should -Be @('PermissionDenied')
+      $result | ConvertTo-Json -Depth 6 | Should -Not -Match 'secret'
+   }
+}

dev/tests/WorkloadFailure.Tests.ps1

@@ -0,0 +1,63 @@
+#Requires -Version 7.4
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+BeforeAll {
+   $script:entrypoint = Join-Path $PSScriptRoot '../Invoke-Dev.ps1'
+   function docker { throw 'Unmocked Docker call refused.' }
+}
+
+Describe 'Early workload client failure' {
+   BeforeEach {
+      $script:state = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N'))
+      @{success = $false; stage = 'native_login_and_channels'; error = 'QqqSessionException'; reason = 'secret-value https://private.invalid/?token=secret'; completed = 0} | ConvertTo-Json | Set-Content (Join-Path $TestDrive 'client-fixture.json')
+      Mock docker {
+         $global:LASTEXITCODE = 0
+         if ($args[0] -eq 'compose')
+         {
+            if ($args -contains 'ps')
+            {
+               if ($args[-1] -eq 'test-client') { return ('c' * 64) }
+               if ($args[-1] -eq 'test-server') { return ('b' * 64) }
+            }
+            return
+         }
+         if ($args[0] -eq 'inspect')
+         {
+            if ($args[1] -eq ('c' * 64)) { return 'false|17' }
+            throw 'SERVER_WAIT_REACHED'
+         }
+         if ($args[0] -eq 'cp')
+         {
+            $fixtureRoot = [IO.Directory]::GetParent([IO.Directory]::GetParent([IO.Directory]::GetParent($args[-1]).FullName).FullName).FullName
+            Copy-Item -LiteralPath (Join-Path $fixtureRoot 'client-fixture.json') -Destination $args[-1]
+            return
+         }
+         if ($args[0] -in @('ps', 'network', 'volume')) { return }
+         throw 'Unexpected fake Docker operation.'
+      }
+   }
+   It 'surfaces the client failure before server waiting and still cleans owned containers' {
+      { & $entrypoint -Action Test -StateDirectory $script:state } | Should -Throw '*Workload client failed at native_login_and_channels (QqqSessionException)*'
+      Should -Invoke docker -ParameterFilter { $args[0] -eq 'inspect' -and $args[1] -eq ('b' * 64) } -Times 0
+      Should -Invoke docker -ParameterFilter { $args[0] -eq 'compose' -and $args -contains 'rm' -and $args -contains '--stop' } -Times 1 -Exactly
+      $result = Get-ChildItem -LiteralPath $script:state -Filter result.json -Recurse
+      (Get-Content -LiteralPath $result.FullName -Raw | ConvertFrom-Json).reason | Should -Be 'secret-value https://private.invalid/?token=secret'
+   }
+   It 'does not print unrecognized stage or exception text' {
+      @{success = $false; stage = 'secret-stage https://private.invalid/'; error = 'secret-error'} | ConvertTo-Json | Set-Content (Join-Path $TestDrive 'client-fixture.json')
+      { & $entrypoint -Action Test -StateDirectory $script:state } | Should -Throw '*Workload client failed at unknown (UnknownFailure)*'
+      Should -Invoke docker -ParameterFilter { $args[0] -eq 'inspect' -and $args[1] -eq ('b' * 64) } -Times 0
+   }
+   It 'fails safely for <Kind> diagnostics and still cleans owned containers' -TestCases @(
+      @{Kind = 'malformed'; Content = '{secret-malformed-json'},
+      @{Kind = 'null'; Content = 'null'},
+      @{Kind = 'oversized'; Content = (@{success = $false; stage = 'input'; error = 'JsonException'; reason = ('s' * 65536)} | ConvertTo-Json -Compress)}
+   ) {
+      param($Content)
+      $Content | Set-Content (Join-Path $TestDrive 'client-fixture.json')
+      { & $entrypoint -Action Test -StateDirectory $script:state } | Should -Throw '*Workload client failed at unknown (UnknownFailure)*'
+      Should -Invoke docker -ParameterFilter { $args[0] -eq 'inspect' -and $args[1] -eq ('b' * 64) } -Times 0
+      Should -Invoke docker -ParameterFilter { $args[0] -eq 'compose' -and $args -contains 'rm' -and $args -contains '--stop' } -Times 1 -Exactly
+   }
+}

docs/OPERATIONS.md

@@ -40,19 +40,137 @@ The host configures resource ceilings through `PrintingQBitConfig.withAdmissionL
 
 `PrintingAdmissionLimits.defaults()` returns these defaults. To override them, construct the record with device/tenant pairs in this order: outstanding jobs, outstanding bytes, retained bytes, hourly admissions, cumulative printers. Values must be positive. Use the same configuration on every QQQ node serving a tenant. Size retained capacity for actual document sizes and the chosen retention period; 10,000 jobs/day is a sizing target, not a measured hardware throughput result. These are logical application byte limits, not an S3 billing limit: object versions, multipart fragments and provider overhead require their own deployment monitoring and lifecycle policy.
 
-Admission is serialized per tenant in SQL before storage writes. Pending and failed upload reservations stay charged until exact-object cleanup succeeds; failed admissions that reached a committed reservation also consume the hourly allowance. Legacy reservations with unknown length conservatively reserve the maximum 20 MiB each, against the tenant when their device is unknown. Existing payloads are backfilled without removal. Apply this additive accounting migration with older application writers stopped; mixed-version writers or direct SQL changes bypass accounting and are unsupported.
+Admission is serialized per tenant in SQL before storage writes. Pending and failed upload reservations stay charged until exact-object cleanup succeeds; failed admissions that reached a committed reservation also consume the hourly allowance. Legacy reservations with unknown length block new allocations until exact cleanup resolves them; a fixed-size guess cannot safely account for configurable document limits. Existing payloads are backfilled without removal. Apply this additive accounting migration with older application writers stopped; mixed-version writers or direct SQL changes bypass accounting and are unsupported.
 
 HTTP 429 means capacity, the rolling-hour allowance, cumulative inventory history, or an existing upload reservation prevents a new allocation. The response explains the category. Reuse the same idempotency/request identity when retrying: a completed matching replay returns its existing job even at capacity or after the original retry source expires. Wait for outstanding work or the hourly window, investigate failed cleanup/storage access, or have the host administrator adjust a justified capacity limit. Retention only removes eligible successful documents; it does not erase failed, uncertain or active work to make space.
 
 Inventory snapshots remain limited to 200 entries. Rotating IDs cannot bypass cumulative history limits, and rejected snapshots leave approval, availability and job references intact. Existing IDs remain updateable when a legacy database already exceeds a limit. Management `GET /printing/v1/admin/devices/{deviceId}/printers` accepts `limit` (1–200, default 200) and opaque `before` from the preceding response's `nextCursor`. The response is `{ "printers": [...], "nextCursor": null | "..." }`, ordered by stored name and row identity. The existing Java `printers()` method returns the first bounded array; use `printersPage()` for additional history. Native QQQ tables retain their own backend paging.
 
+## Device controls and durable action receipts
+
+The native client API is the registered `printing` extension, semantic version
+`1.0.0`, under `/qqq/v1/qbit/printing`. Discover it through QQQ's version endpoint;
+its generated OpenAPI fragment is `src/main/resources/openapi/qqq-v1/printing.yaml`.
+The contract test checks this fragment against the registered endpoint specs and
+the initial semantic compatibility baseline. Core QQQ session authentication and
+credential scopes run before printing operations; the application does not issue
+another kind of user login token.
+
+Every native operation requires the authenticated QQQ principal, `printing_admin`,
+the configured tenant security key, and applicable native table, process and row
+access. Device operations additionally require `X-QQQ-Device-Id` and
+`X-QQQ-Device-Token` as secondary proof. Enrollment at `/devices/enroll` validates
+the user's facility access before consuming the enrollment code and atomically
+binds the device to the core user's stable identity. A legacy unbound device can
+be bound only through explicit `/device/bind` with valid proof and native device
+access. Ordinary requests never bind or transfer ownership implicitly.
+
+`GET /session` returns the current principal and tenant; valid bound device headers
+add the device identity. Native administration can manage another user's device
+when current permissions allow it, without impersonating that user. Queue clear
+and inventory updates authorize affected existing rows before mutation and compare
+the reviewed identity set under the device lock. Claims authorize the exact job
+and printer before dispatch, ordered by creation time then identity. An inaccessible
+printer fails closed rather than granting access through its parent device.
+
+Queue-clear review is bounded to 10,000 jobs. It performs a native Get for each
+job and each distinct printer, with the device checked once. Get-specific policies
+remain effective. Large clears on remote databases have not been performance
+qualified; this review cost is separate from normal claim throughput.
+
+Developer projections that request derived `device_status`, `control_status`, or
+`command_status` must also select `id`. The normal native UI includes it. An
+identity-free projection is rejected rather than returning a fabricated UNKNOWN
+status; the frozen QQQ dependency has no pre-query projection hook for these fields.
+
+Printing selection processes also enforce native table access before extraction
+and preview counts. The printing extract wrapper preserves the core filter,
+callbacks, and tenant row locks, then requires permission enforcement on the
+query. Later review/load checks still reauthorize the selected records.
+
+Authorization uses the native QQQ context established for each request. Host
+authentication and session refresh policies determine when permission changes
+reach that context; printing does not assert that an upstream cached session is
+fresh. Cookie-authenticated unsafe calls must also satisfy the host's Origin/CSRF
+policy. The local host requires its canonical same-origin authority.
+
+In the qualified QQQ 4.1.0-RC.20 runtime, OAuth2 `sessionStoreEnabled` defaults
+to `false`. Ordinary requests and session resume rerun the configured
+`QAuthenticationModuleCustomizerInterface` hooks; the host can load current
+permissions, tenant keys, and account status from its authoritative directory.
+With session caching enabled, a cache hit skips those hooks. That configuration
+requires explicit session-cache invalidation on authorization changes or another
+qualified freshness policy. Periodic `manageSession` calls and token renewal alone
+do not establish current provider roles or immediate account revocation.
+
+TABLE_BASED authentication rereads the session and user rows on each request;
+deleting either prevents resume. A generic user `enabled` column is not enforced
+automatically, and this module does not invoke the OAuth customizer hooks. The
+local host grants its configured account the configured printing role and tenant;
+this is not a general mutable role directory. Qualify the integrating host's
+authorization mapping and provider behavior separately from printing transport.
+
+Device controls use the same tenant-scoped service facade from native management
+and transport adapters. Adapters must authorize the current user, tenant, device,
+and action before calling the facade; a device ID or an actor string is not an
+authorization grant. The legacy `/printing/v1` device bearer transport remains a
+compatibility interface, not a substitute for native QQQ user permissions.
+
+Once a device is bound to a QQQ user, its token is secondary proof only: all
+legacy device endpoints reject it, including claim, content and control polling.
+Existing unbound legacy devices remain usable during migration. New legacy
+enrollment is disabled by default in `PrintingRoutes` and explicitly disabled in
+`PrintingLocalHost`; native enrollment uses `/qqq/v1/qbit/printing/devices/enroll`.
+Only a legacy-only host such as `PrintingDemo` should opt into
+`PrintingRoutes.LegacyEnrollment.ENABLED`. A rejected legacy enrollment does not
+consume the code, which still requires native user and facility authorization.
+
+Pause blocks new claims. Disconnect stops dispatch and inventory publication while
+the authenticated control WebSocket remains available for a reconnect command.
+Neither operation cancels an already submitted spooler job. Resume preserves
+connection state; reconnect preserves pause. Revocation invalidates device proof,
+closes its channel and requires separate local re-enrollment. It cannot be undone
+with resume/reconnect. Desired state, observed revision and last contact are separate facts:
+a successful server action does not prove an offline device applied it.
+
+Queue clear atomically changes only this device's QUEUED jobs to FAILED with the
+existing cancellation reason. It preserves documents, accounting, and history;
+CLAIMED, RECEIVED, SUBMITTING, and uncertain work remain untouched. Claim and clear
+share the device lock across server instances. Spool cancellation accepts only an
+owned job with a recorded spool identity. The agent must independently verify its
+local connection-scoped ownership before asking the operating system to cancel;
+the server never accepts an arbitrary queue name, spool ID, or executable.
+
+Every management action supplies a new `requestId` and a UTC `issuedAt`, retained
+unchanged across retries. A retained matching request returns its existing record;
+a changed body returns 409. Without an existing record, requests older than 15
+minutes return 410, and times over 60 seconds in the future return 400. Review a
+new action explicitly when a form expires. Never silently refresh its time or
+reuse its identity. Terminal records become eligible for bounded cleanup after
+seven days; an unchanged old request still expires after its receipt is removed.
+
+Remote inventory refresh and owned spool cancellation require advertised agent
+capabilities, expire after 15 minutes, and have a limit of 100 pending commands
+per device. Polls deliver at most 20 commands. The retained action history is
+limited to 1,000 records per device, with one additional reserved revocation;
+eligible old terminal records are reclaimed before admission. Capacity returns
+429 explicitly. History pages contain at most 200 records and use the preceding
+`nextCursor`; an expired or foreign cursor cannot disclose another device.
+
+Agents durably journal remote command identity before any effect and return the
+same receipt on duplicate delivery. Expiry stops delivery but does not prove that
+an earlier attempt did not execute: a first late receipt may replace provisional
+EXPIRED with its actual outcome. Once stored, a receipt is immutable; conflicting
+replays return 409. `CANCEL_REQUESTED` means the operating system accepted a
+cancellation request, not that paper was withdrawn or a physical print was undone.
+
 ## Common failures
 
 | Symptom | Check |
 | --- | --- |
 | Enrollment rejected | Code expiration/single use, correct server, administrator-created facility/device enrollment |
 | No printers in QQQ | Service access to Windows queues; local exposure selection; connector enrollment and inventory publication |
-| Printer listed but submission rejected | Both `available` and `enabled`, format capability and 20 MiB decoded-size limit |
+| Printer listed but submission rejected | Both `available` and `enabled`, format capability and configured PDF/ZPL decoded-size limits |
 | Job stays queued | Connector connectivity, selected queue availability and device assignment |
 | Job stays received/submitting after restart | Inspect local journal/spooler; automatic uncertain-output replay is intentionally absent |
 | Printing app missing or access denied | QBit registration, `printing_admin`, matching `printing_tenant`, and correct QQQ backend |

docs/OPERATOR-CATALOG.md

@@ -0,0 +1,67 @@
+# Operator catalog and queue media
+
+This source adds native printing extension 2.3.0 (2.2.0 is the rendering extension and carries no media negotiation). Publication and Windows media
+agent qualification are pending. Existing administrator and device routes keep
+their permissions; this is an additive operator API, not a device bearer API.
+
+Hosts grant `printing_operator` and the `printing_tenant` security key. The native
+`printingSubmit` process remains the domain write permission. Current device and
+printer table/record security, credential scopes and client-channel ceilings apply
+on every operation. Generic job/command history, table writes, enrollment and
+device management remain administrator-only. Hosts may add destination locks.
+Native callbacks cannot replace the initiating actor, session, instance, service
+or row-security context. Submission rechecks current process, credential, channel
+and destination authority after loading/storage callbacks and before commit.
+The backend process is hidden and has no base64-entry form. Echo obtains its user
+selections from the catalog; backend metadata also references native printer and
+format possible-value sources.
+
+- `GET /qqq/v1/qbit/printing/operator/printers?limit=50&after=...` returns at most
+  200 authorized approved/exposed printers, in stable printer-row-ID order. The
+  opaque next cursor advances over at most `limit` candidate rows even if parent
+  device security hides every candidate. Continue until `nextCursor` is null.
+- `POST /qqq/v1/qbit/printing/operator/jobs` accepts `requestId`, `printerRowId`,
+  `title`, `format` (`PDF` or `ZPL`), `contentBase64` and optional `options`. The
+  native printer row determines the device and opaque Windows queue identity.
+  `requestId` is 1–128 characters from letters, digits, `.`, `_`, `:`, `-`.
+  The authenticated actor and tenant scope the stable key; callers cannot supply
+  actor identity or an internal idempotency key. The response is the existing job
+  receipt after durable commit. Changed requests conflict instead of reprinting.
+- `GET /qqq/v1/qbit/printing/operator/requests/{requestId}` returns only that
+  actor's exact accepted request, or 404. It does not enqueue, read document bytes,
+  or initialize settings. Current destination read authority remains required;
+  later loss of exposure alone does not erase the acceptance receipt.
+  Lookup checks the original accepted native printer-row ID. Deleting that row
+  and creating another with the same device/queue pair does not transfer history.
+
+Each catalog entry has `printerRowId`, `deviceId`, `printerId`, effective `name`,
+`deviceName`, `status`, `formats`, `mediaProfiles`, and optional `description` and
+`location`. These names are presentation; the stable row identity selects a queue.
+
+Media profiles report actual Windows queue defaults. Their typed facts are `id`,
+`revision` (lowercase SHA-256), `name`, `widthMicrons`, `heightMicrons`, `dpiX`,
+`dpiY`, `source: WINDOWS_QUEUE_DEFAULT`, `applyMode: DRIVER_DEFAULT`. Unknown or
+unsupported driver facts produce an empty list. The initial client reports one
+configured default; the wire bound is 32. Dimensions are 1–2,000,000 microns and
+DPI is 1–9600. Names are at most 512 characters. Unknown additive reported facts
+are ignored when canonicalizing; known required facts remain validated. Arbitrary
+page-size values are never interpreted as a Windows stock change.
+Profile and selection IDs share the protocol's 128-character URL-safe ID bound.
+
+Select exact reported media with `options.mediaProfile: {id, revision}`. The
+selection is immutable job intent and accepts no extra fields. New submissions
+reject stale/missing profiles before admission/storage writes; exact accepted
+replays remain accepted. The capable Windows agent rechecks its actual current
+default before spooling. Selected-media dispatch requires the current agent
+capability `printer-media-v1`, including after reconnect/downgrade. Legacy
+inventory without profiles clears stale media facts. Omitted selection preserves
+ordinary existing queue behavior. Paper-width/height overrides remain unsupported,
+including when a media selection is supplied.
+
+Generated/retained source authorization belongs to the configured source owner.
+The retained facade shares this operator permission and destination boundary; it
+preserves its atomic accepted source/actor/request binding. Barcode fit and
+encoding remain the renderer's job.
+
+`QUEUED` is durable acceptance; `SPOOLED` means spooler acceptance. Neither is
+physical output confirmation. These tests use synthetic bytes and no real printer.

docs/QUALIFICATION-2026-11-01.md

@@ -0,0 +1,104 @@
+# Server qualification — 2026-11-01
+
+The published server **0.3.0-rc.1** and published Windows **0.3.1-rc.1** Core runtime
+completed the following isolated qualification. No live server, installed service,
+real document, physical printer or external cloud bucket was changed.
+
+## Network workload
+
+These measurements describe the earlier released-artifact fixture runs. The
+portable [Docker developer tooling](../dev/README.md) records its own per-run
+measurements and includes separate default smoke and opt-in burst commands.
+
+The existing Java/.NET interoperability fixture was extended with synthetic work.
+It used the actual QQQ table-authenticated host, native session/device binding,
+WebSocket channel, released Core `PrintWorker`, HTTPS-client code over explicitly
+allowed loopback HTTP, file downloads, and WebSocket receipt acknowledgements.
+Only the physical printer and local fixture journal were substitutes. The server
+persisted real SQL jobs and receipts. Admission limits remained enabled.
+
+| Check | Observed result |
+| --- | --- |
+| Burst workload | 10,000 jobs; two tenants; eight devices |
+| Documents | 1,021-byte synthetic ZPL; exact downloaded bytes checked |
+| Completion | 10,000 SPOOLED rows; 30,000 durable event rows; no pending work |
+| Replay | 400 submit and 400 receipt replays; no duplicates |
+| Isolation | Foreign device binding and tenant job access refused |
+| Accounting | Retained bytes exact; no orphan upload rows |
+| Duration | 96.12 seconds including setup; about 104 jobs/second |
+| Maximum backlog | 7,798 committed jobs; final backlog zero |
+| Working set | Server peak 680 MiB; client peak approximately 85 MiB |
+| Cold persistence | 10,000 rows present; read-only check left DB unchanged |
+
+Burst enqueue-to-terminal-ACK latency was p50 43.30 seconds, p95 62.84 seconds,
+p99 64.66 seconds. These values include intentional queue backlog; they are not
+idle notification latency.
+
+A separate **40-job one-at-a-time** run measured:
+
+| Interval | Median | 95th percentile |
+| --- | ---: | ---: |
+| Received notification to claim completion | 8.72 ms | 27.18 ms |
+| Received notification to verified download completion | 29.74 ms | 49.07 ms |
+| Enqueue to durable terminal receipt acknowledgement | 49.65 ms | 76.56 ms |
+
+The fixture does not periodically poll for jobs. A received notification wakes a
+finite claim/drain operation. Liveness PING messages do not query jobs. These are
+HTTP/WS loopback results, **not HTTPS/WSS, remote network, physical print-speed,
+large-document sustained throughput, or long-duration soak qualification**.
+The fixture journal is not the installed Windows SQLite journal; its recovery
+behavior is covered separately by the Windows tests.
+
+## Existing storage path, current release
+
+The existing S3 qualification harness was rerun against this exact published
+server and its unchanged 204-JAR runtime. All **65 checks / six document round
+trips** passed through native QQQ `StorageAction`, `S3StorageAction`, and AWS SDK
+against one disposable local MinIO container. The run includes actual multipart
+upload above 5 MiB, exact length/hash/MIME, tenant namespaces, immutable-reference
+validation, stable replay, completion-age retention, and protection of active,
+failed, uncertain, fresh, foreign and unrelated objects. The owned container and
+its ephemeral data were removed after identity verification.
+
+This is S3-compatible data-plane evidence. It does not qualify AWS IAM, remote
+TLS, bucket policies, versioning/Object Lock, or a configured production storage
+target. The existing platform-specific key-layout binding guard remains required;
+no shared QQQ library or cross-OS migration behavior was changed.
+
+## Repeatable service regression
+
+`PrintingWorkloadTest` is an opt-in file-backed regression, separate from the
+network fixture. It runs 10,000 real service lifecycles through four pooled SQL
+connections, tests replay and tenant pagination, verifies exact event/byte counts,
+and closes every connection before reopening without schema initialization.
+
+```powershell
+./mvnw.cmd -Pui-demo -Dprinting.qualification.load=true verify
+```
+
+The protocol fixtures must be present at the usual sibling checkout; alternatively
+set `-Dprinting.protocol.fixtures=/path/to/reviewed/fixtures`.
+The full gate passed **119 tests, zero skips and zero Checkstyle violations**.
+A subsequent exact event-count assertion improvement passed its focused workload
+rerun. Default builds skip this explicit workload test; ordinary regression tests
+remain unchanged. The separate development workflow runs cross-platform script
+checks and the real 40-job/S3 Docker smoke on pull requests and main pushes; its
+experimental native-auth run is manual. Hosted results must be checked on the
+submitted commit. No application implementation or dependency changed.
+
+## Scope boundaries
+
+The user's current development/test target is local Docker. AWS/account/IAM or
+remote deployment provisioning is not a prerequisite for this change.
+
+The separate [experimental native-auth profile](../dev/native-auth/README.md)
+passed real Authentik login, denied-user/wrong-Origin checks, logout, short token
+renewal and provider revocation using container-private HTTPS and the pinned
+unreleased QQQ API 1.9 candidate. It does not upgrade this regression's released
+RC.20 dependency or qualify the installed Windows browser callback. The workload
+and S3 measurements above remain HTTP/WS and MinIO evidence, respectively.
+
+Long-duration soak, mid-session account/role changes and sustained physical
+throughput remain separate from these bounded tests and previously confirmed
+individual physical prints. No application implementation, dependency or
+published package version changes in this test/developer-tooling change.

docs/REALTIME.md

@@ -0,0 +1,109 @@
+# Real-time printing host integration
+
+Release candidate [0.3.0-rc.1](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.3.0-rc.1)
+implements printing extension **2.0.0** (wire envelope v1). Upgrade the server
+before the matching Windows connector; a real-time connector rejects a server that advertises only extension
+1.x. There is no timed job/control polling fallback.
+
+## Connection and authorization
+
+The Windows service initiates `wss://<qqq-origin>/qqq/v1/qbit/printing/device/realtime`
+using subprotocol `qqq-printing.v1`. No facility listener or inbound firewall rule
+is required. Plain WebSocket is allowed only for explicit loopback development.
+Configure the cloud ingress to forward WebSocket upgrades, preserve the original
+HTTPS origin and allow the configured heartbeat interval/timeout.
+
+The service discovers authentication through the QQQ UI/UX API and uses the
+standard current QQQ session, client channel and approved bound-device proof.
+Credentials are not URL parameters. Device proof does not replace the user's
+authority. The server validates the current session, user/tenant, channel policy
+and operation permissions; socket establishment does not grant permanent rights.
+Session expiry, logout, revocation and permission denial require correction or
+sign-in through the configured QQQ provider. Reconnect cannot bypass them.
+
+Register the route provider alongside the ordinary native QQQ endpoints:
+
+```java
+server.withAdditionalRouteProviders(List.of(existingHttpRoutes,
+   new PrintingRealtimeRoutes(printingService)));
+```
+
+Use the **same PrintingService instance** in the QBit configuration and route
+provider. `PrintingLocalHost.configure` shows the complete launcher integration.
+The native HTTP claim route requires a connected socket that has applied the
+current desired state and settings. Registering just the older HTTP provider is
+insufficient. Close the provider when its host stops.
+
+## Independent control and document lanes
+
+The socket carries small JSON state, commands, inventory, heartbeats, job events
+and durable receipts. A job notification triggers a finite HTTP claim drain;
+an empty queue waits for another push. No timer repeatedly fetches claims or
+commands. Heartbeats, session renewal and reconnect backoff are lifecycle work,
+not job polling.
+
+Documents use separate outbound same-origin HTTPS transfers. The Windows service
+streams them to protected staging files and checks declared length and SHA-256
+before native submission. The socket reader remains active during a slow download.
+PDF rendering and ZPL spooling receive the verified file rather than a base64
+payload in the control pipe. Limits bound staging, messages and concurrency.
+
+Receipts remain on disk until the server acknowledges their committed IDs. A
+reconnect resynchronizes current state/settings and replays retained receipts.
+An interrupted native submission remains uncertain and is never automatically
+reprinted. A successful spooler submission does not prove paper physically printed.
+
+## Native administrator settings
+
+Printing home links to two standard QQQ processes. They enforce current
+administrator and tenant access on the backend as well as in metadata:
+
+- **Printing connection and limits**: PDF/ZPL size, copies, staging space,
+  concurrent downloads/prints, bandwidth, request/download timeouts, heartbeat,
+  reconnect backoff/jitter, acknowledgment timeout and control message queues.
+  Defaults are 100 MiB PDF, 20 MiB ZPL and one download/print lane. Saved policy
+  changes have a durable revision and are pushed to connected devices.
+- **Printing queue and storage limits**: device/tenant outstanding counts and
+  bytes, retained bytes, hourly allocations and printer counts. New admissions
+  use the persisted policy inside their SQL transaction. Reducing limits preserves
+  existing jobs and history; it does not silently remove documents.
+
+Fields use readable MiB/GiB/seconds with exact conversion, required values and
+cross-field validation. Unsupported client ceilings fail explicitly rather than
+silently clamping. Storage retention remains in the separate native retention
+process, with a one-year default.
+
+HTTP ingress/body limits remain host-owned. The local host derives its upload
+body ceiling at startup from the persisted document limits (including base64
+expansion for legacy submission). Raising a document limit above the running
+transport ceiling requires a host restart or corresponding production ingress
+configuration. Download streaming does not base64-expand documents.
+
+## Host ownership and deployment boundary
+
+Commit wakeups are emitted after SQL commit. A subscription exists before initial
+state reconstruction, closing the empty-claim/reconnect notification race.
+`PrintingRealtimeBus` is an explicit host-owned notification and connection
+ownership seam. The default implementation is in-process; this source does **not**
+provide a distributed broker or claim tested multi-node production support.
+
+Use one writer/application host with its configured service/bus. Multiple route
+providers sharing that explicit in-process bus fence a device's prior connection.
+A multi-node deployment needs a host-provided shared implementation preserving
+both post-commit notifications and single-channel ownership, and its own
+qualification. Separate independent service instances do not magically publish
+notifications to one another.
+
+The existing `/printing/v1` routes remain explicit legacy diagnostic compatibility.
+They are not a real-time fallback and cannot authorize a native bound device.
+The full message and settings contract is in
+[the shared protocol](https://github.com/QRun-IO/qqq-print-protocol).
+
+## Printing API major upgrade
+
+The extension is **2.0.0** because native HTTP claims now require a synchronized
+WebSocket. A published 1.0 HTTP-only connector no longer meets that precondition;
+this is a breaking behavior change even though request bodies remain wire v1.
+The QQQ framework API `/qqq/v1`, extension path `/qbit/printing` and WebSocket
+subprotocol `qqq-printing.v1` remain unchanged. Upgrade server and client together;
+an older client must report upgrade-required instead of using polling fallback.

docs/RETAINED-PRINT-FACADE.md

@@ -0,0 +1,114 @@
+# Retained print acceptance (additive candidate)
+
+This optional Java integration preserves the existing native generation print
+process and the existing printing queue. It adds no device wire fields or REST
+routes. It is disabled until the host supplies
+`PrintingQBitConfig.withRetainedSourceAuthority`. Current `printing_operator`
+(or administrator) authority and native tenant/device/printer record checks
+remain mandatory. Submission also requires the shared `printingSubmit` process
+permission. This grants no device management or generic job-history access.
+
+## Public contract
+
+`RetainedPrintFacade.Request(requestId, sourceLocator, printerRecordId, title,
+optionsJson)` contains no actor or asserted source binding. Request IDs use
+`[A-Za-z0-9._:-]{1,128}`, including owner namespaces such as `echo:<scanId>`.
+`submit` derives the signed-in native actor and returns an immutable
+`Acceptance`; it includes the exact source, job/event identities, tenant,
+initiating actor, destination, title and normalized options JSON, including any
+`mediaProfile` ID/revision. `find` authorizes the same complete request and
+returns that acceptance, null for observed absence, or a conflict for an
+unresolved upload reservation. Reuse the same request identity after a lost
+response. Never convert an unavailable lookup into absence or create another
+intent automatically.
+
+The host-configured `RetainedPrintSourceAuthority.resolve(locator, requestId)`
+must authorize the current native actor, source association and currently
+eligible immutable version. It returns `SourceReference(owner, opaqueReference,
+sha256, sizeBytes, mediaType)`. `opaqueReference` is at most 4000 Java
+characters, stable and canonical under that owner's rules; printing does not
+parse owner-specific fields. The optional Record Files adapter must encode its
+complete version/source/generation-request/initiating-actor/tenant tuple and
+compare generation's committed receipt. Accepted MIME types are
+`application/pdf` and `application/vnd.zebra-zpl`; the current configured
+PDF/ZPL limits apply before the byte read, within the existing integer-length
+storage ceiling. `read(reference, requestId)` must enforce the same current
+permissions and return only those exact bytes. Hash/length verification remains
+in printing's existing submission path. Do not supply arbitrary source
+authorities per request or reconstruct a user session.
+
+Source admission remains the owner's policy. An explicitly configured published
+template may qualify generated output without a per-label release dialog;
+external-upload quarantine is unchanged. Printing performs no automatic release
+and creates no human-release audit. `resolve` must be read-only and must not
+invoke a generation reconciliation operation that can generate or dispatch work.
+
+Source/destination checks surround owner callbacks and precede acceptance.
+Submission refuses an ambient QQQ transaction: queue acceptance is independently
+committed and cannot be rolled back by a caller's transaction. Submission also
+enforces the native job-table credential and channel mutation ceilings; lookup
+uses the corresponding read ceilings without granting generic table access.
+`find` calls no byte reader, submission or event writer, and its option
+normalization cannot initialize settings. It reauthorizes the source and
+destination records, then compares the exact accepted intent; a later exposure,
+media inventory or dispatch-limit change does not reinterpret that historical
+intent. A later permission loss may deny returning a receipt whose job already
+committed; it never authorizes a replacement job.
+
+## Persistence and replay
+
+Existing `printing_job` gains nullable `retained_actor_id`,
+`retained_binding_json`, and `accepted_event_id`. Existing `printing_event`
+gains nullable `event_origin`. `initialize` applies additive upgrades; old
+jobs/events remain unbound/unclassified. None of these internal fields are added
+to the device `JOB_COLUMNS` DTO or native table metadata.
+
+Submission and exact lookup both use the existing tenant admission lock, so an
+in-flight inline acceptance cannot be mistaken for absence. The unique
+`(tenant_id, idempotency_key)` serialize submissions. Retained keys use
+`retained:` plus the request ID. Ordinary/bound collisions refuse. Complete
+normalized intent includes actor, owner reference, content hash/length/media,
+destination, title, options and tenant. The existing storage reservation/orphan
+path is reused; it may commit an upload reservation before writing object
+storage. The final job, retained binding, and server acceptance event commit
+together. Failed acceptance-event insertion rolls back the job. Rollback or
+orphan-cleanup failures are suppressed onto the original failure rather than
+replacing it. Existing initialization widens legacy 300-character titles to
+1024; the bound title preserves exact whitespace and Unicode and is compared on
+replay. Acceptance-event JSON has `type=ACCEPTED`, `origin=SERVER_ACCEPTANCE`,
+`status=QUEUED`; it does not claim device receipt or physical output.
+
+This is atomic acceptance binding inside printing, not a distributed transaction
+over the retained owner's authorization database. Deployment still owns durable
+database/storage settings, bounded provider calls and current session policy.
+
+## Committed observations
+
+`observation(requestId, eventId)` reads only an exact committed event joined to
+the accepted job. New ordinary device events are stamped `DEVICE_OBSERVATION`;
+pre-upgrade unclassified events and server acceptance events cannot be returned
+as device evidence. The current native operator must have current device/printer
+row authority and satisfy the job credential/channel read ceiling. Before
+returning any source metadata, printing calls the configured owner's
+`authorizeObservation(source, requestId)` under the current reporter session,
+then rechecks the current ceiling and destination authority. Its default
+implementation refuses; adapters must explicitly implement their current
+source-observation policy. This callback does not grant content access or
+impersonate the initiating actor. This is an operator-authorized observation
+lookup, not device enrollment or permission to forge reporter identity. The
+optional RF authority adapter must preserve initiating actor separately from
+current reporting actor and map only supported stored states. Neither `SPOOLED`
+nor `SPOOLER_COMPLETED` proves physical output.
+
+## Verification scope
+
+The tests use real H2 transactions and native QQQ row authorization with
+synthetic printers. They never contact a device or emit physical output.
+Coverage includes commit-then-throw acknowledgment loss, concurrent exact
+replay, held-admission-lock lookup, mutation ceilings, owner observation
+refusal, callback revocation, exact content hash/length, configured document
+bounds, title upgrade/replay, read-only historical lookup and original-error
+preservation when rollback fails. Qualification of this adopted source is
+recorded in the session notes; the older peer candidate's test result is not
+evidence for this revision. Cross-QBit integration remains a separate gate. No
+release, install, shared-cache substitution or runtime migration has occurred.

docs/SESSION-STATE.md

@@ -1,18 +1,160 @@
 # Session state — 2026-10-31
 
+## Echo operator/media and retained-source candidate — 2026-11-01
+
+The isolated Echo candidate adds native printing extension **2.3.0** (after the protected-main 2.2.0 rendering extension) on the
+unchanged product `0.4.0-SNAPSHOT` and QQQ `4.1.0-RC.20` dependency tuple.
+`printing_operator` permits the authorized printer/media catalog and exact-actor
+submission/reconciliation without device administration or general job history.
+Reported Windows queue-default media is revision-bound; clients without the current
+`printer-media-v1` capability cannot claim jobs carrying a media selection.
+
+The opt-in retained-source facade shares that boundary and commits immutable
+source/actor/destination/intent plus its server acceptance event inside the existing
+queue transaction. Its owner adapter is required and default-deny; read-only lookup
+never generates content or submits a replacement job. See
+[operator catalog](OPERATOR-CATALOG.md) and
+[retained acceptance](RETAINED-PRINT-FACADE.md) for exact contracts and limits.
+
+Protected main advanced to a rendering release at printing 2.2.0 (header/footer
+chrome, content sections, render-to-PDF) while this candidate was qualified, so the
+operator/media/retained feature was merged onto it and moved to 2.3.0. The earlier
+183-test gate is historical evidence of the pre-merge source only.
+
+Observed after the merge, locally: the OpenAPI contract was regenerated with the
+existing explicit update switch and its 1.0.0 compatibility baseline hash was
+unchanged. A sandbox full verify reported 188 tests with 11 loopback setup errors and
+no assertion failures (environmental). The first actual-user full verify reported 188
+tests, no assertion failures and **one error**:
+`PrintingRealtimeTest.mediaCapabilityIsReplacedOnEveryAuthenticatedHello` failed
+only when JUnit removed its temporary directory. Cause: `PrintingRealtimeRoutes.close()`
+shut its executor down without waiting, so a channel drain still running after the
+host stopped queried a deleted file database and recreated it empty. The fix waits
+(bounded) for running drains, with regression
+`closeWaitsForChannelWorkersAlreadyRunning`. After it, five consecutive focused
+`PrintingRealtimeTest` runs passed (4 tests each, no empty-database warnings) and the
+full `-Pui-demo verify` passed: **189 reported, 188 executed, one intentional opt-in
+workload skip, zero failures/errors, zero Checkstyle violations**; the source-header
+guard over 146 tracked files and staged whitespace checks passed. The earlier failing
+logs are preserved. This is local evidence only: hosted CI on the signed candidate
+head, publication and cross-QBit consumer qualification are pending. The suite runs
+against synthetic H2 fixtures; no live database, connector, printer or shared
+artifact has been changed. The
+experimental API 1.10 used by Echo is a separate owner-controlled tuple and has not
+been substituted for this candidate's qualified RC.20 dependencies. Publication,
+cross-QBit consumer qualification and any physical output remain separate gates.
+
+Native destination and storage callbacks cannot carry stale actor, session,
+credential, channel or row authority into admission, replay or commit. Receipt
+lookup authorizes the original stored printer-row ID; a replacement row with the
+same device/queue pair cannot inherit earlier acceptance history. The regressions
+reproduce both prior paths, verify denial and rollback, and preserve authorized
+read-only observation after the original queue loses exposure. Media IDs are
+bounded to the shared 128-character contract; long device display names remain
+supported without truncation.
+
+## Local Docker development — 2026-11-01
+
+The optional native-auth probe now shares production Core discovery and the
+default workload's printing-major-2 gate, accepting stable 2.1.0 while retaining
+the exact experimental API 1.9/native grant requirement. Its previous exact-2.0.0
+check reproduced a rejection before the fix. Native and default client image
+builds pass 12 and nine fake-HTTP compatibility checks respectively, with zero
+warnings/errors. One fresh provider run against server source `3592dec`
+(printing API 2.1.0) and the reviewed probe correction passed all eight checks.
+All source hashes remained unchanged through completion; independent cleanup
+found zero owned containers, volumes and networks. No installed runtime,
+physical printer or host trust setting changed.
+
+The developer tooling is published on `main` through [PR #21](https://github.com/QRun-IO/qbit-printing/pull/21),
+merged as `3592decba8087439aff5d1b75a9726c72f460cb9`; its tree matches tested
+head `def8d961f3d82a1235f8e45ffbeacb0fbe79c421`. The final hosted
+[development run](https://github.com/QRun-IO/qbit-printing/actions/runs/41324370247)
+passed the actual 40-job HTTP/WS smoke and 65 S3 checks, nine pinned-Core discovery
+compatibility cases, and all 33 script tests on each of Windows and Ubuntu.
+The [Java run](https://github.com/QRun-IO/qbit-printing/actions/runs/41324370253)
+reported 133 tests: 132 executed, one intentionally skipped opt-in workload test,
+zero failures/errors, and zero Checkstyle violations. That workload separately
+passed on the combined source. These are development-tooling publication results,
+not a server release or live runtime upgrade. The experimental API 1.9 candidate
+remains opt-in and is not adopted into the released application dependencies.
+
+The current qualification scope is local Docker only. The new `dev/Invoke-Dev.ps1`
+provides owned Start/Test/Stop commands for a native QQQ TABLE host, dedicated
+MinIO storage and optional real Authentik/PostgreSQL. Source images and the client
+Core archive are pinned. Generated credentials stay in private state outside the
+checkout; no installed connector, live database or physical printer is used.
+
+Portable Docker checks passed: the default 40-job smoke, 65 actual QQQ S3 backend
+checks, and an opt-in 10,000-job/two-tenant/eight-client run with 30,000 durable
+server receipts and 400 submission plus 400 receipt replays. The burst completed
+in 147.856 seconds (about 67.63 jobs/second); its enqueue-to-ACK p95 was 32.984
+seconds while work intentionally queued. This is HTTP/WS with a fake file printer
+and a simple fixture client journal, not TLS, hardware or a long soak claim.
+
+Native TABLE login, identity, frontend asset and logout passed. Real Authentik
+configuration/discovery passed; a registered redirect continued to login and the
+otherwise-identical unregistered redirect was rejected. The released RC.20 host
+still advertises API 1.8 without the native session grant: browser login, renewal
+and the Windows callback are not established by these checks. All owned test
+containers, volumes and networks were removed. Lifecycle/bootstrap regressions
+passed 28 cases including experimental-profile refusal and diagnostic-redaction
+checks; scripts passed parser and PSScriptAnalyzer checks.
+
+The separate opt-in native-auth profile passed eight actual checks against the
+immutable upstream API 1.9 candidate `ecf0f550a0357cec6387c2b54efca128a405a629`:
+ordinary TLS refusal before container-only CA installation, typed-grant discovery,
+real Authentik login through the production Core PKCE client, wrong-Origin cookie
+rejection, denied-user permissions, logout replay refusal, server-side renewal
+after access-token expiry and denial after provider refresh-token revocation.
+The final run exited zero and all owned containers, volumes and networks were
+removed. Earlier failed fixture attempts remain in private evidence; their fixes
+were standard-flow readiness/binding, bounded provider redirects and the correct
+Authentik CSRF header. No authentication check was disabled.
+
+This experimental candidate is not the default released RC.20 runtime or a
+published production dependency upgrade. Container HTTPS and automated real
+provider flows do not qualify the Windows browser callback UI, host trust,
+months-long operation or physical printing. See [local development](../dev/README.md),
+[provider limits](../dev/AUTHENTIK.md) and [native qualification](../dev/native-auth/README.md).
+Earlier release checkpoints below are historical. This developer-tooling merge
+did not publish a new server product release or change the live paired runtime.
+
+## Opt-in service workload regression — 2026-11-01
+
+The combined test/development change also includes a 10,000-job, two-tenant,
+eight-lane file-backed service regression with replay, exact accounting,
+pagination and cold reopen checks. It is opt-in and never accesses a printer.
+The original isolated full gate passed 119 tests with zero Checkstyle violations;
+the final exact receipt-count assertion passed its focused rerun. Its source is
+unchanged when integrated here, and the combined checkout passed one focused
+workload test with zero Checkstyle violations. The earlier released-artifact
+network run and
+40-job idle latency measurements are recorded in
+[qualification evidence](QUALIFICATION-2026-11-01.md), separately from the portable
+Docker run above. No runtime source, dependencies or version changed.
+
+## Active device controls and standard QQQ authentication
+
+Implementation is in the isolated device-controls worktree. Native device/table actions support pause, resume, disconnect, reconnect, revoke, inventory refresh and queued-job clearing; job records support exact owned Windows-job cancellation. Related printers, jobs, pending queue and bounded command history are registered. Derived status separates connection presence, desired state and observed revision. Domain writes use current QQQ permissions; clearing a queue checks every affected job before the transactional mutation.
+
+The primary client transport is the discovered `/qqq/v1/qbit/printing` semantic extension with standard QQQ user sessions and secondary device proof. Authentik requires the shared advertised native PKCE session grant; no private bearer-only fallback substitutes for that authorization. The final isolated Java 21 gate passed **110 tests**, zero failures/errors/skips and zero Checkstyle violations. All 204 runtime dependencies match the frozen approved hashes. Native HTTP, proof/binding denials, explicit permission enforcement, selection count/extraction, FIFO eligibility, queue races, cancellation replay and offline command expiry are covered. Bound device tokens are rejected on legacy routes, and new legacy enrollment defaults off; real HTTP regressions prove there is no secondary-proof downgrade. The actual .NET client passed 23 native table-based authentication/binding/control/logout checks without printers or jobs. Current protected CI and installed/provider acceptance remain pending. No new feature release or local installation has occurred.
+
+The user confirmed all three current Query test prints good. Barcode catalog expansion was removed from printing scope and belongs to document/barcode generation.
+
 ## Query mascot correction
 
 Built-in diagnostic pages and labels now use the official Query dog artwork from [qrun.io/query](https://qrun.io/query), with the exact original asset and provenance recorded alongside the resource. White padding preserves its aspect ratio within the existing layout; warehouse glyphs, media profiles, barcode and print routing are unchanged. All five PDF profiles and three thermal resolutions are covered by the new regression. The isolated full build passed **73 tests with no failures/errors/skips and zero Checkstyle violations**. Generated PDF previews and actual ZPL graphic-field reconstruction were reviewed. The tested resource is packaged and the previous logo is absent.
 
-This server-only correction is not yet deployed or released. The Windows client already requests these server-generated documents; no client icon change is needed. The installed corrective Windows 0.1.9 candidate is connected and passed all 16 UI checks with credentials/history preserved. Publication and fresh branded physical-output confirmation remain pending.
+This server-only correction is published in [v0.1.4-rc.1](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.1.4-rc.1), and local native deployment is accepted. The Windows client already requests these server-generated documents; no client icon change is needed. Installed-client acceptance passed with credentials and history preserved. Physical output from the new Query diagnostics remains unconfirmed.
 
-## Audit candidate 0.1.4-rc.1
+## Published audit release 0.1.4-rc.1
 
-The authorized local paired-host cutover is complete. The exact approved CI package from `09e0995` runs the native QQQ frontend and device API on the existing loopback address. A native backup was independently restored and fully compared before the old H2 host stopped; its closed database was also preserved and checked. Existing pairing, one device, two ready printers, seven jobs and 21 events were retained. The Windows service reconnected automatically. Native login, bounded real-record queries, anonymous/cross-origin/authentication-table denials, logout and the enabled **365-day** retention policy passed. No new print was requested. This local host uses database delivery storage; real dedicated S3 provisioning and remote deployment are deferred by the user's local-first instruction.
+Local paired-host acceptance is complete following verified recovery backups. Native authentication, bounded record queries, anonymous/cross-origin/authentication-table denials, logout and the enabled **365-day** retention policy passed. Pairing and history were preserved, and the connector reconnected automatically. This acceptance used database document storage and did not request a new print. Dedicated production S3 provisioning, IAM and remote deployment remain unqualified.
 
-All required hosted checks pass at `09e0995`, including the approved narrow H2 dependency input. Exact CI JAR SHA256 is `db84552b84d0a2fa62766fe8fcf4ba7414ae57f798629f281abba951d0889422`; all 47 archive-entry payloads match the already qualified `45261d5` package, including 38 implementation classes and all runtime resources. All 204 dependency coordinates match. Fresh verification records 72 passing tests, zero Checkstyle violations, complete scanner evidence and zero Trivy HIGH/CRITICAL findings. Tagged publication and the Windows 0.1.9 installed qualification are still pending.
+All required checks passed for reviewed Query commit `c34883d`; protected merge `412ffbbc` preserves that exact tree. [Release run 41190650664](https://github.com/QRun-IO/qbit-printing/actions/runs/41190650664) passed every build, security and CodeQL gate before publishing assets for signed tag `v0.1.4-rc.1`. The current gate records **73 passing tests and zero Checkstyle violations**. All 204 runtime dependency coordinates are unchanged from the qualified audit runtime. The public JAR, POM and SHA256SUMS passed checksum and GitHub attestation verification, constrained to the exact source commit, tag and release workflow. All 48 JAR entry contents, including 38 implementation classes, match the reviewed Query CI package. Release JAR SHA256: `b31aa58588e2bad6b1ca63e5904906c0379ef75b6d2b550ad1680e668312065b`.
 
-The latest S3 safeguard passes **72 Java tests, zero failures/errors/skips and zero Checkstyle violations**, with independent source review complete. It binds documents to the reviewed physical key layout and native separator using unambiguous ordered JSON. Historical reads, new retries and cleanup reject incompatible bindings before object IO; inline database content and prior retry receipts remain compatible. Old experimental S3 bindings are not silently adopted.
+The preceding S3 safeguard checkpoint passed **72 Java tests, zero failures/errors/skips and zero Checkstyle violations**, with independent source review complete. It binds documents to the reviewed physical key layout and native separator using unambiguous ordered JSON. Historical reads, new retries and cleanup reject incompatible bindings before object IO; inline database content and prior retry receipts remain compatible. Old experimental S3 bindings are not silently adopted.
 
 Actual isolated Windows-to-Linux qualification passed on local candidate JAR SHA256 `9163b5fb89c981b70d2bd416ca3920a17bcbda2fe61eaa7190f050cc27759495` with all 204 runtime libraries verified on both hosts. Read and retry returned 409; cleanup recorded an error with zero removals. A positive-control-checked native SDK observer recorded zero transmissions for those refusals. Content availability, tenant/device retained bytes, admission/orphan/job counts and the exact original object stayed unchanged. The earlier candidate reproduced false expiration of a Windows-key object from Linux; this correction prevents that loss of availability. Portable upstream keys, explicit historical migration and production IAM remain separate work. Fresh hosted checks for this correction and the scoped license input now pass.
 
@@ -26,7 +168,7 @@ The prepared-copy failure was the upstream H2 2.3.232 close-time compaction defe
 
 The earlier H2 license-metadata gate is resolved. [Standards PR #54](https://github.com/KofTwentyTwo/standards/pull/54) merged EX-0013 through normal required checks following explicit user approval. Its separately approved CodeQL repair retains Actions and JavaScript/TypeScript under the advanced security-extended workflow. Printing applies only the approved package input; its fresh [PR gates](https://github.com/QRun-IO/qbit-printing/actions/runs/41185576692) pass. The inventory guard still requires exactly unmodified H2 2.4.240, with 17 passing guard tests; all other license, vulnerability and branch protections remain enforced. See [license evidence and expiry](H2-LICENSE-REVIEW.md).
 
-The audit also fixes native-process replay, tenant-scoped facility selectors, duplicate-output risk preservation, atomic queue/retained-byte/rate admission and bounded printer history. Dedicated QQQ document storage and scheduled retention protect active, failed and uncertain work. Stop older writers before schema/accounting migration and preserve verified recovery copies. See [audit evidence](AUDIT-2026-10-30.md), [operations](OPERATIONS.md) and [storage](STORAGE-AND-RETENTION.md). Real PostgreSQL/S3, remote authentication, multi-node operation and sustained physical throughput remain unqualified. Local cutover and shared-standards publication are complete; tagged audit publication remains pending.
+The audit also fixes native-process replay, tenant-scoped facility selectors, duplicate-output risk preservation, atomic queue/retained-byte/rate admission and bounded printer history. Dedicated QQQ document storage and scheduled retention protect active, failed and uncertain work. Stop older writers before schema/accounting migration and preserve verified recovery copies. See [audit evidence](AUDIT-2026-10-30.md), [operations](OPERATIONS.md) and [storage](STORAGE-AND-RETENTION.md). Real PostgreSQL/S3, remote authentication, multi-node operation and sustained physical throughput remain unqualified. Local acceptance, shared-standards approval and tagged audit publication are complete.
 
 Record Files' **21:54 America/Chicago checkpoint on 2026-10-30** is acknowledged. Its latest typed reader and configured reporting authority are candidate source with focused tests; the verified installed artifact is still pending, and the earlier snapshot is not the final contract. The teams agree on the consumer-owned observation boundary and are resolving identifier bounds and optional spooler-ID canonicalization. Printing still needs its durable accepted source/initiator/job/destination binding, tenant-scoped committed event receipt and legitimate current native reporting identity before an adapter can be enabled. No adapter is enabled, no browser session or fabricated authority is retained, and spool completion is not physical-output confirmation. Standalone byte submission remains independent.
 
@@ -74,3 +216,21 @@ Final QBit UI pass: metadata uses printing_* table/data-source names, printing-p
 
 Durable target correction: core DurableJobsRuntime.effectLoop constructs a system session without user tenant keys. PrintEnqueueEffectTarget now has a private trusted resolver for that system-only outbox path, bound to the current instance PrintingQBitConfig service and its fixed tenant. Inline users retain scope checks; native process authorization is unchanged. Registered-target tests cover system deliver/reconcile, idempotent replay, foreign-tenant device rejection, cached target reuse across instances, and inline wrong/missing-tenant denial.
 `mvnw.cmd -o verify -Pui-demo dependency:build-classpath` passed all 16 tests and zero Checkstyle violations after the durable target correction, explicit disabled table writes, final dashboard timestamps, and frontend RC.37 profile update. UI runtime classpath regenerated at target/ui-runtime-classpath.txt. Primary identifiers remain non-hidden because QQQ excludes hidden fields from ordinary query results; explicit frontend column hints keep them out of the default operational grid.
+
+## Real-time transport implementation resumed — 2026-10-31
+
+User resumed implementation after explicitly rejecting periodic job/control polling. Active isolated worktrees: qbit-printing-wt-realtime, qqq-print-protocol-wt-realtime, qqq-print-agent-wt-job-table (all branch feat/realtime-printing-20261031). Installed 0.2.0-rc.1 remains unchanged and is still polling; do not claim it is real-time.
+
+Protocol extension 1.1.0: client-initiated authenticated WSS, qqq-printing.v1 subprotocol, current QQQ session and secondary bound-device proof. Small state/commands/events/receipts travel directly over WebSocket; separate HTTPS documents stream to protected files. No timed polling fallback. Commit notifications and finite event-triggered claims, bounded concurrency, persistent receipts and reconnect reconciliation are being implemented. Tenant administrator forms expose document, transfer, connection, queue/rate/printer/storage limits. Default PDF limit100MiB, ZPL20MiB; both configurable. Root owns native forms/admission settings, server agent owns route/storage/service, Windows agent owns transport/pipeline, inventory agent completed protocol70definitions/72fixtures and now owns Jobs UI expansion/sorting. No live install or new physical print yet. New-source gates/integration are in progress; previous0.2 gates do not qualify these changes.
+
+## Real-time source verification — 2026-10-31
+
+Server source0.3.0-rc.1 passes117 Java tests and zero Checkstyle violations, including real native-session WebSocket lifecycle, sessionId/sessionUUID, logout/channel rejection, replacement fencing, partial revision acknowledgments, no idle-inventory feedback, and21MiB native storage streaming/integrity. Protocol70definitions/72fixtures passes; both consumer workflows pin signed protocol67be986cb76d6b5d9a9f72cad054193b0d11b0d5. Native admin policy tests cover permission/tenant checks, exact250.5MiB conversion, revision persistence and invalid-capacity rejection. A private actual.NET/Java fixture passed13 functional checks with25MiB content, durable receipt replay, channel replacement and sign-out denial; its initial fixture JVM needed explicit maintenance-thread shutdown handling, so this is not installed lifecycle qualification. Root is preparing the final refreshed fixture run. Current installed0.2 remains unchanged; release/install acceptance is pending.
+
+## Final real-time API gate — 2026-10-31
+
+Native printing extension is now2.0.0, because requiring a synchronized WebSocket for previously HTTP-only native claims is a breaking behavior change. Framework/qqq/v1, wirev1 and qqq-printing.v1 remain unchanged; product0.3.0-rc.1. Full final-source verify passed118tests, zero failures/errors/skips and zero Checkstyle violations. Configured heartbeat timeout now determines dashboard freshness (90s legacy floor) and authorized PING records control-only contact. Published1.0 OpenAPI baseline remains preserved. Protocol repin and final Windows verification are pending; no live deployment.
+
+## Coordinated protocol and cross-runtime verification — 2026-10-31
+
+Current immutable consumer pin is df3729ac632d4a34a3fb8423acef465042a624fc (71definitions/73fixtures); it supersedes earlier67be986 pre-major-correction checkpoints. Final API2.0 Java/Release.NET interoperability passed13 checks with25MiB content and exact durable replay, temporary host stopped and wrapper exit0. Installed0.2 remains unchanged. Windows source gate398tests passed before one final startup recovery regression was added; its definitive gate is still pending. No release/install acceptance claim.

docs/SOURCE-HEADERS.md

@@ -0,0 +1,17 @@
+# Owned source notice check
+
+Run these commands from the repository root with the existing Python 3 interpreter:
+
+```text
+python3 .github/scripts/test-source-headers.py
+python3 .github/scripts/check-source-headers.py
+```
+
+The standard-library checker enforces the scope of the reviewed 2026-11-01 header pass, not an estate-wide licensing or formatting audit. `.github/source-headers.json` names the owned source/config path families, comment syntax, accepted holder/license pairs and explicit exclusion reasons. Python `fnmatch` patterns match slash-containing relative Git paths; new files in those families are covered after they are tracked. Empty selections fail. The checker does not scan untracked build output or modify files.
+
+Only leading language comments count. Copyright text in a string, Python docstring or comment after code is rejected. UTF-8 BOMs, initial shebangs, PowerShell `#Requires` directives and XML declarations are handled before the notice. These declarations cannot be displaced beneath a new notice. PowerShell block comments are recognized only for PowerShell files. Existing years and holders are not rewritten. Complete canonical Apache notices are valid without redundant SPDX; Java still requires the full Apache block. A contradictory SPDX identifier fails.
+
+JSON/schema/fixture/lock data, explicit generated output directories, vendor legal assets and upstream Maven wrappers are excluded with reasons in the policy. Solution/activation/test-runner metadata and `.editorconfig` remain outside this completed pass; their applicable root LICENSE/NOTICE remains authoritative. No broad claim about third-party licensing follows from this check. New owned file types or provenance must be reviewed before changing the allowlist; do not add blanket exclusions to make a failure disappear.
+
+The implementation and its negative tests are intentionally maintained copies across the three printing repositories, with each repository's own copyright/license header and independently reviewed scope. They do not fetch policy or execute source. CI invokes them in existing jobs using the runner's available Python, with no new package or workflow context. Existing native C# IDE0073 and Java Checkstyle conventions remain unchanged.
+This repository accepts Kingsrook, LLC / Apache-2.0 for its reviewed source/build/config families. The existing CI verify job runs the guard.

docs/TODO.md

@@ -1,7 +1,65 @@
 # Follow-up
 
+## Script quality gates
+
+- [x] Pin Ruff and strict Pyright with a locked restore; reject Python outside `.github/scripts/` and zero-file Pyright runs; negative tool probes pass locally.
+- [ ] Observe the new `verify` job steps pass on hosted CI before relying on them.
+
+## Echo integration candidate
+
+- [x] Implement authorized operator catalog, native submission/process permission,
+  exact actor/request lookup and reported driver-default media revisions.
+- [x] Integrate the opt-in atomic retained-source facade using the same queue,
+  current authority, immutable acceptance and exact device-event observation.
+- [x] Close native callback authority changes and preserve the exact accepted
+  printer-row identity during read-only request reconciliation.
+- [x] Complete local combined verification on the merged 2.3.0 candidate: 189
+  reported, 188 executed, one opt-in workload skip, zero failures/errors and
+  Checkstyle violations (the earlier 183-test gate was pre-merge). Preserve exact
+  source, draft protocol fixtures and frozen runtime hashes.
+- [ ] Pass hosted CI on the final signed candidate head; local results do not
+  replace it.
+- [ ] Qualify Echo/Generation's exact core tuple and configured source authority;
+  do not silently adopt experimental core or bypass external-upload admission.
+- [ ] Publish the reviewed additive contract and coordinate client/runtime adoption
+  before owner-operated end-to-end physical acceptance.
+
+## Current local development qualification
+
+- [x] Reuse production discovery and the shared major-2 gate in the optional
+  native-auth probe; reproduce the old 2.1.0 rejection, then pass 12 native and
+  nine default workload fake-HTTP compatibility checks without provider launch.
+- [x] Rerun the eight-check native provider profile once against printing API 2.1.0
+  after review; all eight passed with unchanged source hashes and owned cleanup.
+- [x] Supply portable, owned Docker Start/Test/Stop commands with private synthetic
+  credentials and explicit cleanup; leave the installed pairing untouched.
+- [x] Run the 40-job smoke, 65 real S3 backend checks and 10,000 network jobs with
+  30,000 durable server receipts and replay/isolation assertions.
+- [x] Qualify real Authentik provider discovery and registered/unregistered redirect
+  controls while reporting the released QQQ 1.8 native-grant absence honestly.
+- [x] Qualify the separate experimental API 1.9/container-TLS native login,
+  denied-user/wrong-Origin permissions, logout, short renewal and provider revocation.
+- [x] Include the opt-in 10,000-job pooled-SQL/cold-reopen service regression and
+  preserve separate released-artifact network/idle-latency evidence.
+- [x] Publish developer tooling through PR #21, merged as
+  `3592decba8087439aff5d1b75a9726c72f460cb9`: hosted 40-job/65-S3 checks,
+  33 script tests on both Windows and Ubuntu, and the ordinary Java gate
+  (133 reported, 132 executed, one opt-in skip, zero failures/Checkstyle violations).
+  Keep experimental API 1.9 artifacts opt-in; this merge does not adopt them into
+  the released application or upgrade the live paired runtime.
+
+The older release checklists below are historical context. AWS/cloud-account
+provisioning is outside the user's current local-Docker-only request.
+
+- [x] Complete native device controls, per-record/selection actions, queue/history, dashboard and legacy-boundary integration tests; 110 tests pass with zero Checkstyle violations.
+- [x] Complete 25 actual Windows Core client/native QQQ interoperability checks with table-based authentication, no printers and no jobs.
+- [ ] Complete installed candidate acceptance after protected CI.
+- [ ] Complete standard QQQ discovery/session/device-binding security checks and Windows auth integration; qualify the shared Authentik native grant without a private authentication fork.
+- [x] Review and merge immutable protocol inputs (cc3c4e5), pass protected CI and merge the server and Windows implementations normally. Release tagging and installed acceptance remain separate.
+
 - [x] Replace the test-document logo with the exact official Query dog asset; preserve aspect ratio and verify all PDF/thermal profiles with 73 passing tests, zero Checkstyle violations and reviewed previews.
-- [ ] Deploy and publish the Query correction after fresh required gates, then obtain physical-output confirmation for the updated diagnostic documents.
+- [x] Publish v0.1.4-rc.1 after all required release gates, verify checksums and all three asset attestations, and complete local native deployment acceptance.
+- [x] Obtain user confirmation for all three updated Query diagnostic documents (Letter PDF, Zebra ZPL and Zebra PDF).
 - [x] Correct S3 layout and multiline-prefix binding ambiguity; full isolated gate passes 72 tests with zero Checkstyle violations and independent review complete.
 - [x] Reproduce the actual Windows-to-Linux false-expiration defect, then qualify the corrected runtime: zero SDK requests for refused reads/retries/cleanup and preserved objects, availability and accounting.
 - [x] Pass fresh hosted gates for the S3 correction and approved scoped H2 input; verify exact CI artifacts, all 47 archive payloads and 204 runtime coordinates. Portable upstream keys, historical migration and production IAM remain separate qualification work.
@@ -10,12 +68,12 @@
 - [x] Add the exact reviewed H2 version guard and license attribution/evidence; 17 Python guard tests and workflow lint pass.
 - [x] Approve central H2 metadata record EX-0013 through standards PR #54, apply only its package-scoped workflow input and pass every fresh required check.
 - [x] Qualify registered JVM-hook shutdown on exact `00dd2dd`: native acceptance, Quartz/HTTP shutdown, exit 0 and independent read-only cold inspection before initialization pass. Windows reboot/service-manager behavior remains separate.
-- [x] Perform authorized live paired-host cutover after verified native recovery, closed backup and fresh required gates; preserve pairing, 1 device, 2 ready printers, 7 jobs and 21 events. Native authentication/query/denial/logout, automatic connector reconnection and 365-day retention checks pass.
+- [x] Complete local paired-host acceptance after verified recovery backups and fresh required gates; preserve pairing and history. Native authentication/query/denial/logout, automatic connector reconnection and 365-day retention checks pass.
 
 - [x] Finish audit regressions for native-process replay, strict options/inventory validation, retained duplicate risk and event field bounds; full gate passes 53 tests.
 - [x] Implement admin-configurable document retention (one-year default), bounded scheduled cleanup and existing QQQ object-storage integration, retaining history/receipts and protecting active or uncertain output.
 - [ ] Implement the optional Record Files adapter against its verified frozen contract: durable accepted-source/actor binding, legitimate current reporting identity and committed observation receipt. Adapter remains disabled; standalone printing does not depend on it.
-- [ ] Verify tagged audit release gates, published provenance and deployed-host qualification.
+- [x] Verify v0.1.4-rc.1 release run 41190650664, published JAR/POM/SHA256SUMS provenance and local native deployment acceptance.
 - [x] Historical audit PR #10 checkpoint aeac1a6 passed hosted checks; current H2/native qualification and remaining license gate are recorded above.
 - [x] Complete the independent baseline scan and current-source reviews of all five findings and remediations.
 - [x] Add authenticated native QQQ local host sharing paired data with device routes and the existing scheduler; 65 tests/zero Checkstyle pass and independent source review found no blocker.
@@ -30,7 +88,8 @@
 - [x] Confirm physical built-in ZPL and PDF output on the connected Zebra; scanning and measured alignment remain separate checks below.
 - [x] Add separate synthetic native QQQ frontend preview host.
 - [x] Replace identifier text inputs with tenant-scoped, device-dependent selectors and add table/record actions.
-- [ ] Qualify deployed QQQ host integration.
+- [x] Qualify authenticated local QQQ host integration with preserved pairing/history and native retention scheduling.
+- [ ] Qualify remote QQQ host deployment and production authentication/facility policy.
 - [x] Separate local printer availability from server approval and block withdrawn queues.
 - [x] Prepare public repository documentation, license, CI and GitHub prerelease artifacts.
 - [x] Verify remote CI/security and publish v0.1.0-rc.1 JAR/POM/checksum assets.
@@ -38,7 +97,9 @@
 - [x] Implement the dedicated QQQ object-storage document backend; live S3/IAM qualification remains pending configuration.
 - [ ] Logical destination mappings.
 - [x] Run the coordinated Java gate for profile migration, long text and 10,000-row bounded-history regressions; included in the passing 28-test v0.1.3-rc.1 gate.
-- [ ] Qualify sustained throughput separately from synthetic bounded-history tests.
+- [ ] Qualify long-duration soak and sustained physical throughput separately
+  from the completed bounded network/fake-printer workloads; see
+  [qualification evidence](QUALIFICATION-2026-11-01.md).
 - [x] Device-scoped test/retry/cancel/queued-job routes and native record/table cancellation/reprint review, explicit duplicate-risk consent and retry idempotency.
 - [x] Implement admin document retention and bounded scheduled cleanup, default 365 days.
 - [ ] Server-side job expiry and operational alerts.
@@ -70,4 +131,12 @@ The Windows gate, MSI rebuild, installed UI acceptance, release evidence and fre
 - [ ] Obtain explicit barcode scan and measured alignment confirmation; successful spooling is not physical acceptance.
 
 - [x] Complete independent review after the five baseline security findings are remediated; current details are in SESSION-STATE.md.
-- [ ] Complete deployed-host and real S3 qualification; source tests are not deployment evidence.
+- [ ] Complete remote deployment and production S3/IAM qualification; local native acceptance and isolated storage tests do not establish these.
+
+## Real-time upgrade (active)
+
+- [ ] Complete authenticated outbound WebSocket transport and automatic durable recovery; remove production job/control polling fallback.
+- [ ] Verify concurrent control while large streamed documents download, bounds/cleanup, real concurrency and exact event replay.
+- [ ] Verify native administrator limits forms, live policy delivery, admission overrides and configurable document sizes.
+- [ ] Complete consistent sortable/expandable Windows Jobs and Printers tables.
+- [ ] Run coordinated server/client/protocol gates and cross-runtime native integration before packaging/installing.

package-lock.json

@@ -0,0 +1,51 @@
+{
+  "name": "@qrun-io/qbit-printing-script-quality",
+  "version": "0.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@qrun-io/qbit-printing-script-quality",
+      "version": "0.0.0",
+      "license": "Apache-2.0",
+      "devDependencies": {
+        "pyright": "1.1.414"
+      },
+      "engines": {
+        "node": ">=24"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/pyright": {
+      "version": "1.1.414",
+      "resolved": "https://registry.npmjs.org/pyright/-/pyright-1.1.414.tgz",
+      "integrity": "sha512-FPZZb51jepDX4eP7TEYDeNFtmE3WgwkkEcJpvH3/QmUSsj0EAy3LXu+xB4T/FWDejtsXlCfFr/rbWFjwuwuXww==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "pyright": "index.js",
+        "pyright-langserver": "langserver.index.js"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@qrun-io/qbit-printing-script-quality",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Development-only script quality tooling for QBit Printing; no runtime dependency.",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "pyright": "1.1.414"
+  },
+  "packageManager": "npm@11.19.1"
+}

pom.xml

@@ -1,10 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2026 Kingsrook, LLC
+  SPDX-License-Identifier: Apache-2.0
+-->
+
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent><groupId>com.kingsrook</groupId><artifactId>qbit-build-parent</artifactId><version>2.0.0</version><relativePath/></parent>
    <groupId>com.kingsrook.qbits</groupId>
    <artifactId>qbit-printing</artifactId>
-   <version>0.1.4-rc.1</version>
+   <version>0.4.0-SNAPSHOT</version>
    <name>QQQ Printing</name>
    <licenses><license><name>Apache License, Version 2.0</name><url>https://www.apache.org/licenses/LICENSE-2.0</url></license></licenses>
    <properties>

pyproject.toml

@@ -0,0 +1,13 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+[project]
+name = "qbit-printing-script-quality"
+version = "0.0.0"
+requires-python = ">=3.13"
+
+[dependency-groups]
+dev = ["ruff==0.17.3"]
+
+[tool.uv]
+package = false

ruff.toml

@@ -0,0 +1,56 @@
+# Copyright 2026 Kingsrook, LLC
+# SPDX-License-Identifier: Apache-2.0
+# Based on K22 fbfc8d2cf3b5e16ae9750b04cf9de1794f1e7152.
+# KofTwentyTwo Python lint + format configuration (K22-CODE-PY). Copy to the repo root
+# (or merge into [tool.ruff] in pyproject.toml). `ruff format --check` and `ruff check`
+# run in CI and pre-commit with zero findings allowed.
+target-version = "py313"
+include = [".github/scripts/*.py"]
+extend-exclude = [".venv", "node_modules", "dist", "target", "bin", "obj"]
+# Kingsrook: no practical line-length limit (ruff's maximum is 320).
+line-length = 320
+# Kingsrook: 3-space indentation. Ruff's formatter supports it fully; pycodestyle's
+# "multiple of four" rules (E111/E114) are therefore not selected.
+indent-width = 3
+
+[format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+docstring-code-format = true
+
+[lint]
+select = [
+   "F",     # pyflakes
+   "E4", "E7", "E9", "W",  # pycodestyle errors that are layout-independent
+   "I",     # isort: no wildcard imports, ordered
+   "N",     # pep8-naming
+   "UP",    # pyupgrade
+   "B",     # bugbear
+   "S",     # bandit security
+   "BLE",   # blind except
+   "T20",   # print statements: use logging (Kingsrook logging rule)
+   "ERA",   # commented-out code (Kingsrook: no zombie code)
+   "FIX",   # FIXME/TODO must be resolved or tracked
+   "TD",    # TODO format: author and issue link
+   "PTH",   # pathlib over os.path
+   "RET", "SIM", "C4", "PIE", "PL", "RUF",
+   "ANN",   # type annotations on every function
+   "D",     # docstrings on modules, classes, functions
+   "LOG", "G",  # logging hygiene
+]
+ignore = [
+   "D203",  # conflicts with D211
+   "D213",  # conflicts with D212
+   "TD003", # issue link is enforced by review, not regex
+]
+
+[lint.per-file-ignores]
+".github/scripts/check-*.py" = ["T201"] # CLI diagnostics are the public stdout contract, not application logging.
+".github/scripts/test-*.py" = ["S101", "PLR2004"] # Synthetic assertions and explicit boundary values.
+
+[lint.pydocstyle]
+convention = "pep257"
+
+[lint.flake8-tidy-imports]
+ban-relative-imports = "all"

src/main/java/com/kingsrook/qbits/printing/PrintingAdmission.java

@@ -153,6 +153,10 @@ final class PrintingAdmission
     ***************************************************************************/
    static void reserve(Connection connection, String tenant, String device, String id, int bytes, PrintingAdmissionLimits limits) throws SQLException
    {
+      if(number(connection, "SELECT COUNT(*) FROM printing_document_orphan WHERE tenant_id=? AND content_length IS NULL", tenant) != 0)
+      {
+         throw new PrintingException(429, "An old upload has an unknown document size; complete exact orphan cleanup before admitting new documents");
+      }
       if(number(connection, "SELECT COUNT(*) FROM printing_resource_usage WHERE tenant_id=? AND device_id=?", tenant, device) == 0)
       {
          execute(connection, "INSERT INTO printing_resource_usage VALUES (?, ?, 0)", tenant, device);

src/main/java/com/kingsrook/qbits/printing/PrintingAdmissionSettings.java

@@ -0,0 +1,178 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import javax.sql.DataSource;
+import java.math.BigDecimal;
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.util.List;
+import java.util.Objects;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** Tenant admission overrides are read in the same transaction as admission.
+ *******************************************************************************/
+public class PrintingAdmissionSettings
+{
+   private static final List<String> FIELDS = List.of("deviceOutstandingJobs", "tenantOutstandingJobs", "deviceOutstandingBytes", "tenantOutstandingBytes",
+      "deviceRetainedBytes", "tenantRetainedBytes", "deviceJobsPerHour", "tenantJobsPerHour", "devicePrinters", "tenantPrinters");
+   private static final long MAX_EXACT_JSON_INTEGER = 9_007_199_254_740_991L;
+   private final DataSource source;
+   private final String tenant;
+   private final PrintingAdmissionLimits defaults;
+
+
+
+   /***************************************************************************
+    ** The host supplies immutable defaults until an administrator saves an override.
+    ***************************************************************************/
+   public PrintingAdmissionSettings(DataSource source, String tenant, PrintingAdmissionLimits defaults)
+   {
+      this.source = Objects.requireNonNull(source);
+      this.tenant = Objects.requireNonNull(tenant);
+      this.defaults = Objects.requireNonNull(defaults);
+   }
+
+
+
+   /***************************************************************************
+    ** The enclosing service ensures the tenant settings row before public reads.
+    ***************************************************************************/
+   public JSONObject get() throws SQLException
+   {
+      try(Connection connection = source.getConnection())
+      {
+         return (json(effective(connection)));
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Validate all limits before one atomic tenant-scoped update.
+    ***************************************************************************/
+   public JSONObject save(JSONObject requested) throws SQLException
+   {
+      PrintingAdmissionLimits limits = parse(requested);
+      JSONObject value = json(limits);
+      try(Connection connection = source.getConnection(); var update = connection.prepareStatement("UPDATE printing_settings SET admission_policy_json=? WHERE tenant_id=?"))
+      {
+         update.setString(1, value.toString());
+         update.setString(2, tenant);
+         if(update.executeUpdate() != 1)
+         {
+            throw new SQLException("The tenant admission settings row is unavailable");
+         }
+      }
+      return (value);
+   }
+
+
+
+   /***************************************************************************
+    ** Do not open a nested connection while a queue transaction holds its locks.
+    ***************************************************************************/
+   public PrintingAdmissionLimits effective(Connection connection) throws SQLException
+   {
+      try(var query = connection.prepareStatement("SELECT admission_policy_json FROM printing_settings WHERE tenant_id=?"))
+      {
+         query.setString(1, tenant);
+         try(var rows = query.executeQuery())
+         {
+            if(!rows.next())
+            {
+               return (defaults);
+            }
+            String stored = rows.getString(1);
+            return (stored == null ? defaults : parse(new JSONObject(stored)));
+         }
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Every configured limit is explicit, positive and exactly representable.
+    ***************************************************************************/
+   private static PrintingAdmissionLimits parse(JSONObject value)
+   {
+      if(!value.keySet().equals(java.util.Set.copyOf(FIELDS)))
+      {
+         throw new IllegalArgumentException("Specify all admission limits without unknown fields");
+      }
+      try
+      {
+         return (new PrintingAdmissionLimits(integer(value, "deviceOutstandingJobs"), integer(value, "tenantOutstandingJobs"),
+            number(value, "deviceOutstandingBytes"), number(value, "tenantOutstandingBytes"), number(value, "deviceRetainedBytes"), number(value, "tenantRetainedBytes"),
+            integer(value, "deviceJobsPerHour"), integer(value, "tenantJobsPerHour"), integer(value, "devicePrinters"), integer(value, "tenantPrinters")));
+      }
+      catch(ArithmeticException exception)
+      {
+         throw new IllegalArgumentException("Admission counts must fit the supported integer range", exception);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Counts follow the database's integer representation without truncation.
+    ***************************************************************************/
+   private static int integer(JSONObject value, String field)
+   {
+      return (Math.toIntExact(number(value, field)));
+   }
+
+
+
+   /***************************************************************************
+    ** Reject quoted numbers, fractions, overflow and disabled capacity boundaries.
+    ***************************************************************************/
+   private static long number(JSONObject value, String field)
+   {
+      if(!(value.opt(field) instanceof Number number))
+      {
+         throw new IllegalArgumentException(field + " must be a positive integer");
+      }
+      long parsed = new BigDecimal(number.toString()).longValueExact();
+      if(parsed < 1 || parsed > MAX_EXACT_JSON_INTEGER)
+      {
+         throw new IllegalArgumentException(field + " is outside the supported positive range");
+      }
+      return (parsed);
+   }
+
+
+
+   /***************************************************************************
+    ** Native forms and host defaults share one stable field vocabulary.
+    ***************************************************************************/
+   private static JSONObject json(PrintingAdmissionLimits value)
+   {
+      return (new JSONObject().put("deviceOutstandingJobs", value.deviceOutstandingJobs()).put("tenantOutstandingJobs", value.tenantOutstandingJobs())
+         .put("deviceOutstandingBytes", value.deviceOutstandingBytes()).put("tenantOutstandingBytes", value.tenantOutstandingBytes())
+         .put("deviceRetainedBytes", value.deviceRetainedBytes()).put("tenantRetainedBytes", value.tenantRetainedBytes())
+         .put("deviceJobsPerHour", value.deviceJobsPerHour()).put("tenantJobsPerHour", value.tenantJobsPerHour())
+         .put("devicePrinters", value.devicePrinters()).put("tenantPrinters", value.tenantPrinters()));
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingAgentAuthorization.java

@@ -0,0 +1,132 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.util.List;
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+
+/** Secondary proof binds a device to the already authenticated native QQQ principal. */
+public final class PrintingAgentAuthorization
+{
+   public static final String DEVICE_HEADER = "X-QQQ-Device-Id";
+   public static final String TOKEN_HEADER = "X-QQQ-Device-Token";
+
+
+   /** No independent authentication module or permanent service user. */
+   private PrintingAgentAuthorization()
+   {
+   }
+
+
+   /** Bind only on the explicit endpoint; all ordinary requests require the existing owner. */
+   public static String device(String id, String token, boolean bind) throws Exception
+   {
+      String principal = PrintingControlAuthorization.principal();
+      PrintingControlAuthorization.record(PrintingTables.DEVICE, id);
+      PrintingProcesses.currentService().authorizeAgent(id, token, principal, bind);
+      return (id);
+   }
+
+
+   /** Resolve a wire printer identity through native row security, not a raw SQL lookup. */
+   static QRecord printer(String device, String printer) throws QException
+   {
+      List<QRecord> rows = PrintingControlAuthorization.query(new QueryInput().withTableName(PrintingTables.PRINTER)
+         .withFilter(new QQueryFilter(new QFilterCriteria("device_id", QCriteriaOperator.EQUALS, device))
+            .withCriteria(new QFilterCriteria("printer_id", QCriteriaOperator.EQUALS, printer)).withLimit(1))).getRecords();
+      if(rows.isEmpty())
+      {
+         throw new QPermissionDeniedException("Printer is not accessible");
+      }
+      return (PrintingControlAuthorization.record(PrintingTables.PRINTER, rows.getFirst().getValueString("id")));
+   }
+
+
+   /** Inventory absence updates existing rows too, so authorize the complete bounded inventory. */
+   static Set<String> inventory(String device) throws Exception
+   {
+      Set<String> authorized = new java.util.HashSet<>();
+      String cursor = null;
+      do
+      {
+         JSONObject page = PrintingProcesses.currentService().printersPage(device, 200, cursor);
+         JSONArray printers = page.getJSONArray("printers");
+         for(int index = 0; index < printers.length(); index++)
+         {
+            authorized.add(printer(device, printers.getJSONObject(index).getString("printerId")).getValueString("id"));
+            if(authorized.size() > 10000)
+            {
+               throw new PrintingException(429, "Inventory exceeds the bounded native review limit");
+            }
+         }
+         cursor = page.isNull("nextCursor") ? null : page.getString("nextCursor");
+      }
+      while(cursor != null);
+      // Even an empty inventory must have native table READ access.
+      PrintingControlAuthorization.query(new QueryInput().withTableName(PrintingTables.PRINTER)
+         .withFilter(new QQueryFilter(new QFilterCriteria("device_id", QCriteriaOperator.EQUALS, device)).withLimit(1)));
+      return (authorized);
+   }
+
+
+   /** Select with native row security, then dispatch only that exact authorized identity. */
+   static JSONObject claim(String device) throws Exception
+   {
+      QQueryFilter formats = new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR);
+      for(String format : List.of("PDF", "ZPL"))
+      {
+         formats.withSubFilter(new QQueryFilter(new QFilterCriteria("format", QCriteriaOperator.EQUALS, format))
+            .withCriteria(new QFilterCriteria(PrintingTables.PRINTER + ".formats", QCriteriaOperator.CONTAINS, "\"" + format + "\"")));
+      }
+      List<QRecord> rows = PrintingControlAuthorization.query(new QueryInput().withTableName(PrintingTables.JOB)
+         .withQueryJoin(new QueryJoin(PrintingTables.PRINTER))
+         .withFilter(new QQueryFilter(new QFilterCriteria("device_id", QCriteriaOperator.EQUALS, device))
+            .withCriteria(new QFilterCriteria("status", QCriteriaOperator.IN, List.of("QUEUED", "CLAIMED")))
+            .withCriteria(new QFilterCriteria(PrintingTables.PRINTER + ".enabled", QCriteriaOperator.EQUALS, 1))
+            .withCriteria(new QFilterCriteria(PrintingTables.PRINTER + ".available", QCriteriaOperator.EQUALS, 1))
+            .withSubFilter(formats)
+            .withOrderBy(new QFilterOrderBy("created_at", true)).withOrderBy(new QFilterOrderBy("id", true)).withLimit(20))).getRecords();
+      for(QRecord row : rows)
+      {
+         String id = row.getValueString("id");
+         PrintingControlAuthorization.job(device, id);
+         JSONObject result = PrintingProcesses.currentService().claimForJob(device, id);
+         if(!result.isNull("job"))
+         {
+            return (result);
+         }
+      }
+      return (new JSONObject().put("job", JSONObject.NULL));
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingApiSchemas.java

@@ -0,0 +1,193 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.middleware.javalin.schemabuilder.ToSchema;
+import com.kingsrook.qqq.openapi.model.Schema;
+import com.kingsrook.qqq.openapi.model.Type;
+
+
+/** Explicit typed native request/response contracts, namespaced independently from core schemas. */
+final class PrintingApiSchemas
+{
+   /** Static schema definitions. */
+   private PrintingApiSchemas()
+   {
+   }
+
+
+   /** Shared wire components describe every field; no opaque JSON blob substitutes for a contract. */
+   static Map<String, Schema> components()
+   {
+      Map<String, Schema> schemas = new LinkedHashMap<>();
+      add(schemas, "Empty", fields());
+      add(schemas, "Acknowledgment", fields("accepted", bool()), "accepted");
+      add(schemas, "Session", fields("principalId", text(200), "tenantId", text(200), "deviceId", id()), "principalId", "tenantId");
+      add(schemas, "EnrollmentRequest", fields("enrollmentCode", text(128), "deviceName", text(1024), "agentVersion", text(100)), "enrollmentCode", "deviceName", "agentVersion");
+      add(schemas, "Enrollment", fields("protocolVersion", number(), "deviceId", id(), "deviceToken", text(128).withDescription("Private device proof, returned once; never log."), "pollIntervalSeconds", number()), "protocolVersion", "deviceId", "deviceToken", "pollIntervalSeconds");
+      add(schemas, "Profile", fields("name", text(512).withNullable(true), "description", text(4096).withNullable(true), "location", text(512).withNullable(true)));
+      add(schemas, "MediaSelection", fields("id", id(), "revision", text(64)), "id", "revision");
+      add(schemas, "MediaProfile", fields("id", id(), "revision", text(64), "name", text(512), "widthMicrons", number(), "heightMicrons", number(), "dpiX", number(), "dpiY", number(),
+         "source", enumeration("WINDOWS_QUEUE_DEFAULT"), "applyMode", enumeration("DRIVER_DEFAULT")), "id", "revision", "name", "widthMicrons", "heightMicrons", "dpiX", "dpiY", "source", "applyMode");
+      add(schemas, "OperatorPrinter", fields("printerRowId", id(), "deviceId", id(), "printerId", id(), "name", text(1024), "deviceName", text(1024), "description", text(4096), "location", text(512), "status", text(40), "formats", array(enumeration("PDF", "ZPL")), "mediaProfiles", array(ref("MediaProfile"))),
+         "printerRowId", "deviceId", "printerId", "name", "deviceName", "status", "formats", "mediaProfiles");
+      add(schemas, "OperatorCatalog", fields("printers", array(ref("OperatorPrinter")), "nextCursor", text(200).withNullable(true)), "printers", "nextCursor");
+      add(schemas, "OperatorSubmit", fields("requestId", text(128), "printerRowId", id(), "title", text(1024), "format", enumeration("PDF", "ZPL"), "contentBase64", text(Integer.MAX_VALUE), "options", ref("Options")),
+         "requestId", "printerRowId", "title", "format", "contentBase64");
+      add(schemas, "HeartbeatRequest", fields("agentVersion", text(100), "profile", ref("Profile")), "agentVersion");
+      add(schemas, "Heartbeat", fields("serverTime", time()), "serverTime");
+      add(schemas, "Printer", fields("printerId", id(), "name", text(1024), "driverName", text(1024), "portName", text(1024), "status", enumeration("READY", "OFFLINE", "PAUSED", "ERROR", "UNKNOWN"), "formats", array(enumeration("PDF", "ZPL")), "mediaProfiles", array(ref("MediaProfile")), "displayName", text(512), "description", text(4096), "location", text(512)), "printerId", "name", "formats");
+      add(schemas, "InventoryRequest", fields("printers", array(ref("Printer"))), "printers");
+      add(schemas, "Options", fields("copies", number(), "scale", enumeration("ACTUAL_SIZE", "FIT"), "mediaProfile", ref("MediaSelection"), "paperWidthMm", new Schema().withType(Type.NUMBER), "paperHeightMm", new Schema().withType(Type.NUMBER)));
+      add(schemas, "Job", fields("jobId", id(), "deviceId", id(), "printerId", id(), "title", text(1024), "format", enumeration("PDF", "ZPL"), "contentSha256", text(64), "contentLength", number(), "options", ref("Options"), "createdAt", time(), "status", enumeration("QUEUED", "CLAIMED", "RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED", "FAILED", "OUTCOME_UNKNOWN"), "message", text(2048), "spoolerJobId", id()), "jobId", "deviceId", "printerId", "title", "format", "contentSha256", "contentLength", "options", "createdAt", "status");
+      add(schemas, "Claim", fields("job", ref("Job").withNullable(true)), "job");
+      add(schemas, "Jobs", fields("jobs", array(ref("Job"))), "jobs");
+      add(schemas, "EventRequest", fields("eventId", id(), "status", enumeration("RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED", "FAILED", "OUTCOME_UNKNOWN"), "message", text(2048), "spoolerJobId", id()), "eventId", "status");
+      add(schemas, "TestRequest", fields("requestId", id(), "printerId", id(), "format", enumeration("PDF", "ZPL"), "testProfile", text(40)), "requestId", "printerId", "format");
+      add(schemas, "RetryRequest", fields("requestId", id(), "confirmDuplicateRisk", bool()), "requestId");
+      add(schemas, "DesiredState", fields("revision", number(), "dispatchPaused", bool(), "connectionState", enumeration("CONNECTED", "DISCONNECTED")), "revision", "dispatchPaused", "connectionState");
+      add(schemas, "ControlPollRequest", fields("controlVersion", number(), "agentVersion", text(100), "capabilities", array(enumeration("REFRESH_INVENTORY", "CANCEL_SPOOL", "printer-media-v1")), "lastAppliedRevision", number()), "controlVersion", "agentVersion", "capabilities", "lastAppliedRevision");
+      add(schemas, "Command", fields("commandId", id(), "requestId", id(), "action", enumeration("REFRESH_INVENTORY", "CANCEL_SPOOL"), "createdAt", time(), "expiresAt", time(), "jobId", id()), "commandId", "requestId", "action", "createdAt", "expiresAt");
+      add(schemas, "ControlPoll", fields("controlVersion", number(), "serverTime", time(), "pollIntervalSeconds", number(), "desiredState", ref("DesiredState"), "commands", array(ref("Command"))), "controlVersion", "serverTime", "pollIntervalSeconds", "desiredState", "commands");
+      add(schemas, "ReceiptRequest", fields("receiptId", id(), "outcome", enumeration("INVENTORY_REFRESHED", "CANCEL_REQUESTED", "ALREADY_ABSENT", "OWNERSHIP_MISMATCH", "UNSUPPORTED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"), "completedAt", time(), "message", text(1024)), "receiptId", "outcome", "completedAt");
+      Schema actions = enumeration("PAUSE_DISPATCH", "RESUME_DISPATCH", "DISCONNECT", "RECONNECT", "REVOKE", "REFRESH_INVENTORY", "CLEAR_QUEUE", "CANCEL_SPOOL");
+      add(schemas, "ActionRequest", fields("requestId", id(), "issuedAt", time(), "action", actions, "jobId", id()), "requestId", "issuedAt", "action");
+      add(schemas, "Action", fields("commandId", id(), "requestId", id(), "issuedAt", time(), "deviceId", id(), "action", actions, "status", enumeration("PENDING", "SUCCEEDED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"), "createdAt", time(), "expiresAt", time(), "jobId", id(), "resultCode", text(80), "cancelledJobCount", number(), "receipt", ref("ReceiptRequest")), "commandId", "requestId", "issuedAt", "deviceId", "action", "status", "createdAt", "expiresAt");
+      add(schemas, "Actions", fields("commands", array(ref("Action")), "nextCursor", text(128).withNullable(true)), "commands", "nextCursor");
+      return (schemas);
+   }
+
+
+   /** Every schema has the extension prefix required by the native registry. */
+   static String name(String shortName)
+   {
+      return ("Printing" + shortName + "V1");
+   }
+
+
+   /** Refer to one typed reusable component. */
+   static Schema ref(String name)
+   {
+      return (new Schema().withRefToSchema(name(name)));
+   }
+
+
+   /** Bounded Unicode text. */
+   static Schema text(int limit)
+   {
+      return (new Schema().withType(Type.STRING).withMaxLength(limit));
+   }
+
+
+   /** SchemaBuilder customization retains explicit required fields unsupported by the base RC20 model. */
+   private record Shape(Map<String, Schema> properties, List<String> required) implements ToSchema
+   {
+      @Override
+      public Schema toSchema()
+      {
+         return (new RequiredSchema(required).withType(Type.OBJECT).withProperties(properties));
+      }
+   }
+
+
+   /** Required is a standard OpenAPI keyword missing from RC20's base Schema bean. */
+   public static class RequiredSchema extends Schema
+   {
+      private final List<String> required;
+
+      /** Retain the explicit protocol field requirements. */
+      public RequiredSchema(List<String> required)
+      {
+         this.required = required;
+      }
+
+      /** Published by the core Jackson schema serializer. */
+      public List<String> getRequired()
+      {
+         return (required);
+      }
+   }
+
+
+   /** Build typed object fields without map arity limits. */
+   private static Map<String, Schema> fields(Object... pairs)
+   {
+      Map<String, Schema> fields = new LinkedHashMap<>();
+      for(int index = 0; index < pairs.length; index += 2)
+      {
+         fields.put((String) pairs[index], (Schema) pairs[index + 1]);
+      }
+      return (fields);
+   }
+
+
+   /** Publish a customized typed schema. */
+   private static void add(Map<String, Schema> target, String name, Map<String, Schema> properties, String... required)
+   {
+      target.put(name(name), new Shape(properties, List.of(required)).toSchema());
+   }
+
+
+   /** Protocol identifier. */
+   private static Schema id()
+   {
+      return (text(128));
+   }
+
+
+   /** UTC wire timestamp. */
+   private static Schema time()
+   {
+      return (text(40).withFormat("date-time").withDescription("RFC3339 UTC ending in uppercase Z."));
+   }
+
+
+   /** Exact JSON integer, never a stringified numeric value. */
+   private static Schema number()
+   {
+      return (new Schema().withType(Type.INTEGER));
+   }
+
+
+   /** Required booleans must never be inferred from missing fields. */
+   private static Schema bool()
+   {
+      return (new Schema().withType(Type.BOOLEAN));
+   }
+
+
+   /** Closed action or status vocabulary. */
+   private static Schema enumeration(String... values)
+   {
+      return (new Schema().withType(Type.STRING).withEnumValues(List.of(values)));
+   }
+
+
+   /** Homogeneous typed arrays. */
+   private static Schema array(Schema items)
+   {
+      return (new Schema().withType(Type.ARRAY).withItems(items));
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingChrome.java

@@ -0,0 +1,149 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+
+
+/*******************************************************************************
+ ** The header and footer every printed page carries, whatever the document:
+ **
+ **   <app>                                         <server> · <user> · <printed at>
+ **   <title / breadcrumb>
+ **   ...
+ **   <footer note: a grid's filter and sort>
+ **   <footer: "qqq ui 1.0.0 · server">                                Page n of m
+ **
+ ** Clients send the fields as process values (headerApp, headerTitle,
+ ** headerServer, headerUser, headerPrintedAt, footerLeft, footerNote) so the
+ ** text matches what the user saw (their date format, the app's name, the
+ ** breadcrumb). Missing fields fall back to the instance's branding name, the
+ ** session user, the current instant and "QQQ printing".
+ *******************************************************************************/
+public record PrintingChrome(String app, String title, String server, String user, String printedAt, String footerLeft, String footerNote)
+{
+   /***************************************************************************
+    ** The fields from process values, with server-side defaults.
+    ***************************************************************************/
+   public static PrintingChrome from(RunBackendStepInput input, String fallbackTitle)
+   {
+      return (new PrintingChrome(
+         value(input, "headerApp", defaultApp()),
+         value(input, "headerTitle", fallbackTitle),
+         value(input, "headerServer", ""),
+         value(input, "headerUser", defaultUser()),
+         value(input, "headerPrintedAt", Instant.now().truncatedTo(ChronoUnit.SECONDS).toString()),
+         value(input, "footerLeft", "QQQ printing"),
+         value(input, "footerNote", "")));
+   }
+
+
+
+   /***************************************************************************
+    ** Defaults only (documents rendered outside a process).
+    ***************************************************************************/
+   public static PrintingChrome defaults(String title)
+   {
+      return (new PrintingChrome(defaultApp(), title == null ? "" : title, "", defaultUser(), Instant.now().truncatedTo(ChronoUnit.SECONDS).toString(), "QQQ printing", ""));
+   }
+
+
+
+   /***************************************************************************
+    ** The same chrome with a footer note (a grid's filter and sort).
+    ***************************************************************************/
+   public PrintingChrome withFooterNote(String note)
+   {
+      return (new PrintingChrome(app, title, server, user, printedAt, footerLeft, footerNote == null || footerNote.isBlank() ? (note == null ? "" : note) : footerNote));
+   }
+
+
+
+   /***************************************************************************
+    ** The same chrome with this title when it has none.
+    ***************************************************************************/
+   public PrintingChrome withTitleIfBlank(String fallback)
+   {
+      return (title != null && !title.isBlank() ? this : new PrintingChrome(app, fallback, server, user, printedAt, footerLeft, footerNote));
+   }
+
+
+
+   /***************************************************************************
+    ** The right side of the first header line.
+    ***************************************************************************/
+   String headerRight()
+   {
+      StringBuilder out = new StringBuilder();
+      for(String part : new String[] {server, user, printedAt})
+      {
+         if(part != null && !part.isBlank())
+         {
+            out.append(out.isEmpty() ? "" : " · ").append(part);
+         }
+      }
+      return (out.toString());
+   }
+
+
+
+   /***************************************************************************
+    ** A string value, or the default when absent or blank (bounded length).
+    ***************************************************************************/
+   private static String value(RunBackendStepInput input, String name, String fallback)
+   {
+      String value = input == null ? null : input.getValueString(name);
+      String chosen = value == null || value.isBlank() ? fallback : value;
+      return (chosen == null ? "" : PrintingRecordDocuments.truncate(chosen.strip(), 300));
+   }
+
+
+
+   /***************************************************************************
+    ** The instance's branding name, else "QQQ".
+    ***************************************************************************/
+   private static String defaultApp()
+   {
+      try
+      {
+         var branding = QContext.getQInstance() == null ? null : QContext.getQInstance().getBranding();
+         return (branding != null && branding.getAppName() != null ? branding.getAppName() : "QQQ");
+      }
+      catch(RuntimeException exception)
+      {
+         return ("QQQ");
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** The session user's name, else blank.
+    ***************************************************************************/
+   private static String defaultUser()
+   {
+      return (QContext.getQSession() == null || QContext.getQSession().getUser() == null || QContext.getQSession().getUser().getFullName() == null ? "" : QContext.getQSession().getUser().getFullName());
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingCommandStatus.java

@@ -0,0 +1,139 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.time.Instant;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Effective command status never requires an offline device to poll again.
+ ** Recorded status and durable receipts remain unchanged by native reads.
+ *******************************************************************************/
+public class PrintingCommandStatus implements TableCustomizerInterface
+{
+   private static final Set<String> DEPENDENCIES = Set.of("id", "status", "expires_at");
+   private static final Set<String> TERMINAL = Set.of("SUCCEEDED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN");
+
+
+
+   /***************************************************************************
+    ** Enrich only the requested virtual field, preserving the caller's projection.
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postQuery(QueryOrGetInputInterface input, List<QRecord> records) throws QException
+   {
+      Set<String> selected = input instanceof QueryInput query ? query.getFieldNamesToInclude() : null;
+      if(selected != null && !selected.contains("command_status"))
+      {
+         return (records);
+      }
+      if(selected != null && !selected.contains("id"))
+      {
+         throw new QException("Select id with derived command status");
+      }
+      Map<String, QRecord> dependencies = dependencies(records);
+      Instant now = Instant.now();
+      for(QRecord record : records)
+      {
+         QRecord values = dependencies.getOrDefault(record.getValueString("id"), record);
+         record.setValue("command_status", effective(values, now));
+      }
+      return (records);
+   }
+
+
+
+   /***************************************************************************
+    ** Dependency-only native queries preserve permissions and tenant locks.
+    ** They are bounded by the selected IDs and cannot recurse into enrichment.
+    ***************************************************************************/
+   private static Map<String, QRecord> dependencies(List<QRecord> records) throws QException
+   {
+      ArrayList<String> ids = new ArrayList<>();
+      for(QRecord record : records)
+      {
+         if(!record.getValues().keySet().containsAll(DEPENDENCIES) && record.getValueString("id") != null)
+         {
+            ids.add(record.getValueString("id"));
+         }
+      }
+      Map<String, QRecord> result = new HashMap<>();
+      for(int first = 0; first < ids.size(); first += 200)
+      {
+         List<String> page = ids.subList(first, Math.min(first + 200, ids.size()));
+         QueryInput input = new QueryInput().withTableName(PrintingTables.COMMAND).withFieldNamesToInclude(DEPENDENCIES)
+            .withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.IN, page).withLimit(page.size()));
+         input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+         for(QRecord row : new QueryAction().execute(input).getRecords())
+         {
+            result.put(row.getValueString("id"), row);
+         }
+      }
+      return (result);
+   }
+
+
+
+   /***************************************************************************
+    ** A terminal receipt wins; a pending command needs a valid expiry observation.
+    ***************************************************************************/
+   static String effective(QRecord record, Instant now)
+   {
+      String status = record.getValueString("status");
+      if(status != null && TERMINAL.contains(status))
+      {
+         return (status);
+      }
+      if(!"PENDING".equals(status))
+      {
+         return ("UNKNOWN");
+      }
+      String expiresAt = record.getValueString("expires_at");
+      if(expiresAt == null || expiresAt.isBlank())
+      {
+         return ("UNKNOWN");
+      }
+      try
+      {
+         return (Instant.parse(expiresAt).isBefore(now) ? "EXPIRED" : "PENDING");
+      }
+      catch(DateTimeParseException exception)
+      {
+         return ("UNKNOWN");
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingControlAuthorization.java

@@ -0,0 +1,186 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.json.JSONObject;
+
+
+/** Common current-user authorization for native UI and semantic API management. */
+public final class PrintingControlAuthorization
+{
+   /** Static authorization facade. */
+   private PrintingControlAuthorization()
+   {
+   }
+
+
+   /** Core user references, never emails or request-body identity, determine attribution. */
+   public static String principal() throws QException
+   {
+      if(QContext.getQSession() == null || QContext.getQSession().getUser() == null
+         || QContext.getQSession().getUser().getIdReference() == null || QContext.getQSession().getUser().getIdReference().isBlank())
+      {
+         throw new QAuthenticationException("Sign in to continue");
+      }
+      new PrintingAdminPermission().checkPermissionsThrowing(new RunBackendStepInput(), null);
+      PrintingProcesses.currentService();
+      return (QContext.getQSession().getUser().getIdReference());
+   }
+
+
+   /** Native GetAction applies table access, field protection, and current record security. */
+   public static QRecord record(String table, String id) throws QException
+   {
+      principal();
+      if(id == null || id.isBlank())
+      {
+         throw new QPermissionDeniedException("Record is not accessible");
+      }
+      GetInput input = new GetInput();
+      input.setTableName(table);
+      input.setPrimaryKey(id);
+      input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      QRecord row = new GetAction().execute(input).getRecord();
+      if(row == null)
+      {
+         throw new QPermissionDeniedException("Record is not accessible");
+      }
+      return (row);
+   }
+
+
+   /** Operations without an existing row still require native table read authority. */
+   public static void table(String table) throws QException
+   {
+      principal();
+      query(new QueryInput().withTableName(table).withFilter(new QQueryFilter().withLimit(1)));
+   }
+
+
+   /** Explicit enforcement remains effective inside native process action scopes. */
+   static QueryOutput query(QueryInput input) throws QException
+   {
+      input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      return (new QueryAction().execute(input));
+   }
+
+
+   /** A job operation must also authorize its device and exact printer record. */
+   public static QRecord job(String deviceId, String jobId) throws QException
+   {
+      QRecord row = record(PrintingTables.JOB, jobId);
+      if(!deviceId.equals(row.getValueString("device_id")))
+      {
+         throw new QPermissionDeniedException("Job is not assigned to this device");
+      }
+      record(PrintingTables.DEVICE, deviceId);
+      QRecord printer = record(PrintingTables.PRINTER, row.getValueString("printer_row_id"));
+      if(!deviceId.equals(printer.getValueString("device_id")))
+      {
+         throw new QPermissionDeniedException("Printer is not assigned to this device");
+      }
+      return (row);
+   }
+
+
+   /** The native process permission remains the domain write authority; generic table writes stay disabled. */
+   public static void process(String name) throws QException
+   {
+      principal();
+      PermissionsHelper.checkProcessPermissionThrowing(new RunBackendStepInput().withProcessName(name), name);
+   }
+
+
+   /** Current users can manage authorized devices without impersonating the enrolled agent owner. */
+   public static JSONObject deviceAction(String deviceId, JSONObject request) throws Exception
+   {
+      String actor = principal();
+      record(PrintingTables.DEVICE, deviceId);
+      PrintingDeviceProcesses.Action selected = null;
+      for(PrintingDeviceProcesses.Action action : PrintingDeviceProcesses.Action.values())
+      {
+         if(action.wire.equals(request.optString("action")))
+         {
+            selected = action;
+         }
+      }
+      if(selected == null)
+      {
+         throw new PrintingException(400, "Invalid device action");
+      }
+      process(selected.process);
+      PrintingService service = PrintingProcesses.currentService();
+      String existing = service.existingDeviceAction(deviceId, request.optString("requestId"));
+      if(existing != null)
+      {
+         QRecord receipt = record(PrintingTables.COMMAND, existing);
+         if(receipt.getValueString("job_id") != null)
+         {
+            job(deviceId, receipt.getValueString("job_id"));
+         }
+         return (service.deviceAction(deviceId, request, actor));
+      }
+      Set<String> queue = null;
+      if("CLEAR_QUEUE".equals(selected.wire))
+      {
+         queue = service.queuedJobIdsForControl(deviceId);
+         Set<String> printers = new java.util.HashSet<>();
+         for(String id : queue)
+         {
+            QRecord queued = record(PrintingTables.JOB, id);
+            if(!deviceId.equals(queued.getValueString("device_id")))
+            {
+               throw new QPermissionDeniedException("Job is not assigned to this device");
+            }
+            printers.add(queued.getValueString("printer_row_id"));
+         }
+         for(String printerId : printers)
+         {
+            QRecord printer = record(PrintingTables.PRINTER, printerId);
+            if(!deviceId.equals(printer.getValueString("device_id")))
+            {
+               throw new QPermissionDeniedException("Printer is not assigned to this device");
+            }
+         }
+      }
+      if("CANCEL_SPOOL".equals(selected.wire))
+      {
+         job(deviceId, request.optString("jobId"));
+      }
+      return (service.deviceAction(deviceId, request, actor, queue));
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingDemo.java

@@ -46,7 +46,7 @@ public final class PrintingDemo
       int port = Integer.parseInt(System.getenv().getOrDefault("QQQ_PRINT_PORT", "18081"));
       PrintingService service = new PrintingService(new DriverDataSource(url, "sa", ""), "demo");
       service.initialize();
-      PrintingRoutes routes = new PrintingRoutes(service, context -> MessageDigest.isEqual(adminToken.getBytes(StandardCharsets.UTF_8), PrintingRoutes.bearer(context).getBytes(StandardCharsets.UTF_8)));
+      PrintingRoutes routes = new PrintingRoutes(service, context -> MessageDigest.isEqual(adminToken.getBytes(StandardCharsets.UTF_8), PrintingRoutes.bearer(context).getBytes(StandardCharsets.UTF_8)), PrintingRoutes.LegacyEnrollment.ENABLED);
       Javalin app = Javalin.create(config ->
       {
          config.http.maxRequestSize = 29 * 1024 * 1024;

src/main/java/com/kingsrook/qbits/printing/PrintingDeviceControls.java

@@ -0,0 +1,542 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.time.Instant;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+import org.json.JSONArray;
+import org.json.JSONObject;
+import static com.kingsrook.qbits.printing.PrintingService.query;
+import static com.kingsrook.qbits.printing.PrintingService.update;
+
+
+/** Durable device controls share the device lock with dispatch and submission. */
+final class PrintingDeviceControls
+{
+   private static final Set<String> ACTIONS = Set.of("PAUSE_DISPATCH", "RESUME_DISPATCH", "DISCONNECT", "RECONNECT", "REVOKE", "REFRESH_INVENTORY", "CLEAR_QUEUE", "CANCEL_SPOOL");
+   private static final Set<String> REMOTE = Set.of("REFRESH_INVENTORY", "CANCEL_SPOOL");
+   private final DataSource source;
+   private final String tenant;
+
+
+   /** Bind to the same immutable tenant and pool as the queue. */
+   PrintingDeviceControls(DataSource source, String tenant)
+   {
+      this.source = source;
+      this.tenant = tenant;
+   }
+
+
+   /** Add compatible default state and a bounded durable command ledger. */
+   static void initialize(Connection connection) throws SQLException
+   {
+      for(String sql : new String[] {
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS dispatch_paused INTEGER DEFAULT 0 NOT NULL",
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS connection_state VARCHAR(20) DEFAULT 'CONNECTED' NOT NULL",
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_revision BIGINT DEFAULT 0 NOT NULL",
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_version INTEGER DEFAULT 0 NOT NULL",
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_capabilities VARCHAR(200) DEFAULT '[]' NOT NULL",
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_last_poll_at VARCHAR(40)",
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_applied_revision BIGINT DEFAULT 0 NOT NULL",
+         "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS revoked_at VARCHAR(40)",
+         "CREATE TABLE IF NOT EXISTS printing_device_command (id VARCHAR(36) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, device_id VARCHAR(36) NOT NULL REFERENCES printing_device(id), request_id VARCHAR(128) NOT NULL, action VARCHAR(40) NOT NULL, job_id VARCHAR(36), actor VARCHAR(200) NOT NULL, request_json VARCHAR(2000) NOT NULL, status VARCHAR(40) NOT NULL, created_at VARCHAR(40) NOT NULL, expires_at VARCHAR(40) NOT NULL, result_code VARCHAR(80), cancelled_job_count INTEGER, receipt_json VARCHAR(8000), UNIQUE(tenant_id,device_id,request_id))",
+         "CREATE INDEX IF NOT EXISTS printing_command_owner_idx ON printing_device_command(tenant_id,device_id,created_at,id)",
+         "CREATE INDEX IF NOT EXISTS printing_command_pending_idx ON printing_device_command(tenant_id,device_id,status,expires_at)"
+      })
+      {
+         try(var statement = connection.prepareStatement(sql))
+         {
+            statement.execute();
+         }
+      }
+   }
+
+
+   /** Pure status projection never returns credential verifiers. */
+   static JSONObject state(JSONObject row)
+   {
+      JSONObject result = new JSONObject().put("supported", row.getInt("control_version") == 1)
+         .put("capabilities", new JSONArray(row.getString("control_capabilities")))
+         .put("lastAppliedRevision", row.getLong("control_applied_revision"))
+         .put("desiredState", new JSONObject().put("revision", row.getLong("control_revision"))
+            .put("dispatchPaused", row.getInt("dispatch_paused") == 1).put("connectionState", row.getString("connection_state")));
+      if(row.has("control_last_poll_at"))
+      {
+         result.put("lastPollAt", row.getString("control_last_poll_at"));
+      }
+      return (result);
+   }
+
+
+   /** Strict action input and original receipt enforce replay before any side effect. */
+   JSONObject action(String deviceId, JSONObject request, String actor) throws SQLException
+   {
+      return (action(deviceId, request, actor, null));
+   }
+
+
+   /** A native authorized queue snapshot must still match after taking the device lock. */
+   JSONObject action(String deviceId, JSONObject request, String actor, Set<String> authorizedQueue) throws SQLException
+   {
+      fields(request, Set.of("requestId", "issuedAt", "action", "jobId"));
+      String requestId = text(request, "requestId", 128);
+      if(!requestId.matches("[A-Za-z0-9._-]+"))
+      {
+         throw new PrintingException(400, "Invalid requestId");
+      }
+      String action = text(request, "action", 40);
+      if(!ACTIONS.contains(action) || request.has("jobId") != "CANCEL_SPOOL".equals(action))
+      {
+         throw new PrintingException(400, "Invalid device action");
+      }
+      String jobId = "CANCEL_SPOOL".equals(action) ? text(request, "jobId", 36) : null;
+      if(actor == null || actor.isBlank() || actor.length() > 200)
+      {
+         throw new PrintingException(400, "A bounded authenticated actor is required");
+      }
+      try(Connection connection = source.getConnection())
+      {
+         connection.setAutoCommit(false);
+         try
+         {
+            JSONObject device = lock(connection, deviceId, false);
+            List<JSONObject> old = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND request_id=?", tenant, deviceId, requestId);
+            if(!old.isEmpty())
+            {
+               if(!new JSONObject(old.getFirst().getString("request_json")).similar(request))
+               {
+                  throw new PrintingException(409, "Request identity was already used for a different action");
+               }
+               connection.commit();
+               return (record(old.getFirst()));
+            }
+            Instant issued;
+            try
+            {
+               issued = Instant.parse(utc(request, "issuedAt"));
+            }
+            catch(java.time.format.DateTimeParseException exception)
+            {
+               throw new PrintingException(400, "Invalid action time");
+            }
+            Instant current = Instant.now();
+            if(issued.isBefore(current.minusSeconds(900)))
+            {
+               throw new PrintingException(410, "Action request expired; review a new action explicitly");
+            }
+            if(issued.isAfter(current.plusSeconds(60)))
+            {
+               throw new PrintingException(400, "Action time is too far in the future");
+            }
+            if(device.getInt("enabled") != 1 || device.has("revoked_at"))
+            {
+               throw new PrintingException(409, "Revoked devices require a new local enrollment");
+            }
+            if(!REMOTE.contains(action) && !Set.of("CLEAR_QUEUE", "REVOKE").contains(action) && device.getLong("control_revision") >= 9007199254740991L)
+            {
+               throw new PrintingException(409, "Control revision capacity reached");
+            }
+            expire(connection, deviceId);
+            update(connection, "DELETE FROM printing_device_command WHERE id IN (SELECT id FROM printing_device_command WHERE tenant_id=? AND device_id=? AND status<>'PENDING' AND created_at<? AND expires_at<? ORDER BY created_at,id LIMIT 200)", tenant, deviceId, Instant.now().minusSeconds(7 * 86400).toString(), Instant.now().toString());
+            long history = count(connection, "SELECT COUNT(*) AS n FROM printing_device_command WHERE tenant_id=? AND device_id=?", tenant, deviceId);
+            if(history >= 1000 && !"REVOKE".equals(action))
+            {
+               throw new PrintingException(429, "Device control receipt capacity reached; receipts are retained and revocation remains available");
+            }
+            String id = UUID.randomUUID().toString();
+            String now = current.toString();
+            String expires = current.plusSeconds(900).toString();
+            String result = null;
+            Integer cancelled = null;
+            if(REMOTE.contains(action))
+            {
+               if(device.getInt("control_version") != 1 || !new JSONArray(device.getString("control_capabilities")).toList().contains(action))
+               {
+                  throw new PrintingException(409, "CONTROL_UNSUPPORTED");
+               }
+               if(count(connection, "SELECT COUNT(*) AS n FROM printing_device_command WHERE tenant_id=? AND device_id=? AND status='PENDING'", tenant, deviceId) >= 100)
+               {
+                  throw new PrintingException(429, "Too many pending device commands");
+               }
+               if(jobId != null)
+               {
+                  List<JSONObject> jobs = query(connection, "SELECT id,status,spooler_job_id FROM printing_job WHERE tenant_id=? AND device_id=? AND id=?", tenant, deviceId, jobId);
+                  if(jobs.isEmpty())
+                  {
+                     throw new PrintingException(404, "Job not found");
+                  }
+                  if(!Set.of("SPOOLED", "SPOOLER_COMPLETED").contains(jobs.getFirst().getString("status")) || jobs.getFirst().optString("spooler_job_id").isBlank())
+                  {
+                     throw new PrintingException(409, "Only an owned job with a recorded spool identity can be canceled");
+                  }
+               }
+            }
+            else if("CLEAR_QUEUE".equals(action))
+            {
+               if(authorizedQueue != null)
+               {
+                  Set<String> currentQueue = new java.util.HashSet<>();
+                  for(JSONObject row : query(connection, "SELECT id FROM printing_job WHERE tenant_id=? AND device_id=? AND status='QUEUED' LIMIT 10001", tenant, deviceId))
+                  {
+                     currentQueue.add(row.getString("id"));
+                  }
+                  if(!currentQueue.equals(authorizedQueue))
+                  {
+                     throw new PrintingException(409, "The queue changed; review the current authorized jobs before retrying");
+                  }
+               }
+               cancelled = update(connection, "UPDATE printing_job SET status='FAILED',message=? WHERE tenant_id=? AND device_id=? AND status='QUEUED'", PrintingService.CANCELED_BEFORE_DISPATCH, tenant, deviceId);
+               result = "QUEUED_JOBS_CANCELLED";
+            }
+            else if("REVOKE".equals(action))
+            {
+               update(connection, "UPDATE printing_device SET enabled=0,token_hash=?,revoked_at=?,dispatch_paused=1,connection_state='DISCONNECTED',control_revision=? WHERE tenant_id=? AND id=?", UUID.randomUUID().toString(), now, Math.min(9007199254740991L, device.getLong("control_revision") + 1), tenant, deviceId);
+               update(connection, "UPDATE printing_device_command SET status='OUTCOME_UNKNOWN' WHERE tenant_id=? AND device_id=? AND status='PENDING'", tenant, deviceId);
+               result = "CREDENTIAL_REVOKED";
+            }
+            else
+            {
+               int paused = device.getInt("dispatch_paused");
+               String connected = device.getString("connection_state");
+               if("PAUSE_DISPATCH".equals(action))
+               {
+                  paused = 1;
+               }
+               if("RESUME_DISPATCH".equals(action))
+               {
+                  paused = 0;
+               }
+               if("DISCONNECT".equals(action))
+               {
+                  connected = "DISCONNECTED";
+               }
+               if("RECONNECT".equals(action))
+               {
+                  connected = "CONNECTED";
+               }
+               update(connection, "UPDATE printing_device SET dispatch_paused=?,connection_state=?,control_revision=control_revision+1 WHERE tenant_id=? AND id=?", paused, connected, tenant, deviceId);
+               result = "DESIRED_STATE_UPDATED";
+            }
+            update(connection, "INSERT INTO printing_device_command (id,tenant_id,device_id,request_id,action,job_id,actor,request_json,status,created_at,expires_at,result_code,cancelled_job_count) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
+               id, tenant, deviceId, requestId, action, jobId, actor, request.toString(), REMOTE.contains(action) ? "PENDING" : "SUCCEEDED", now, expires, result, cancelled);
+            JSONObject response = record(command(connection, deviceId, id));
+            connection.commit();
+            return (response);
+         }
+         catch(Exception exception)
+         {
+            connection.rollback();
+            throw exception;
+         }
+      }
+   }
+
+
+   /** Independent outbound control traffic remains available while disconnected. */
+   JSONObject poll(String deviceId, JSONObject request) throws SQLException
+   {
+      fields(request, Set.of("controlVersion", "agentVersion", "capabilities", "lastAppliedRevision"));
+      if(integer(request, "controlVersion") != 1)
+      {
+         throw new PrintingException(400, "Unsupported control version");
+      }
+      String version = text(request, "agentVersion", 100);
+      long applied = integer(request, "lastAppliedRevision");
+      if(!(request.opt("capabilities") instanceof JSONArray capabilities) || capabilities.length() > 3
+         || capabilities.toList().stream().anyMatch(value -> !REMOTE.contains(value) && !"printer-media-v1".equals(value)) || Set.copyOf(capabilities.toList()).size() != capabilities.length())
+      {
+         throw new PrintingException(400, "Invalid control capabilities");
+      }
+      try(Connection connection = source.getConnection())
+      {
+         connection.setAutoCommit(false);
+         try
+         {
+            JSONObject device = lock(connection, deviceId, true);
+            if(applied > device.getLong("control_revision"))
+            {
+               throw new PrintingException(409, "Unknown control revision");
+            }
+            applied = Math.max(applied, device.getLong("control_applied_revision"));
+            String now = Instant.now().toString();
+            update(connection, "UPDATE printing_device SET control_version=1,control_capabilities=?,control_last_poll_at=?,control_applied_revision=?,agent_version=?,last_seen_at=? WHERE tenant_id=? AND id=?",
+               capabilities.toString(), now, applied, version, now, tenant, deviceId);
+            expire(connection, deviceId);
+            JSONArray commands = new JSONArray();
+            for(JSONObject row : query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND status='PENDING' AND (action<>'REFRESH_INVENTORY' OR ?='CONNECTED') ORDER BY created_at,id LIMIT 20", tenant, deviceId, device.getString("connection_state")))
+            {
+               JSONObject value = record(row);
+               JSONObject delivery = new JSONObject();
+               for(String key : List.of("commandId", "requestId", "action", "createdAt", "expiresAt", "jobId"))
+               {
+                  if(value.has(key))
+                  {
+                     delivery.put(key, value.get(key));
+                  }
+               }
+               commands.put(delivery);
+            }
+            connection.commit();
+            return (new JSONObject().put("controlVersion", 1).put("serverTime", now).put("pollIntervalSeconds", 5)
+               .put("desiredState", state(device).getJSONObject("desiredState")).put("commands", commands));
+         }
+         catch(Exception exception)
+         {
+            connection.rollback();
+            throw exception;
+         }
+      }
+   }
+
+
+   /** An immutable receipt records observation, never rewrites printing outcomes. */
+   JSONObject receipt(String deviceId, String commandId, JSONObject receipt) throws SQLException
+   {
+      fields(receipt, Set.of("receiptId", "outcome", "completedAt", "message"));
+      if(!text(receipt, "receiptId", 128).matches("[A-Za-z0-9._-]+"))
+      {
+         throw new PrintingException(400, "Invalid receiptId");
+      }
+      String outcome = text(receipt, "outcome", 40);
+      try
+      {
+         Instant.parse(utc(receipt, "completedAt"));
+      }
+      catch(java.time.format.DateTimeParseException exception)
+      {
+         throw new PrintingException(400, "Invalid receipt time");
+      }
+      if(receipt.has("message") && (!(receipt.opt("message") instanceof String message) || message.length() > 1024 || message.indexOf('\0') >= 0))
+      {
+         throw new PrintingException(400, "Invalid receipt message");
+      }
+      if(receipt.toString().length() > 8000)
+      {
+         throw new PrintingException(400, "Receipt is too large");
+      }
+      try(Connection connection = source.getConnection())
+      {
+         connection.setAutoCommit(false);
+         try
+         {
+            lock(connection, deviceId, true);
+            JSONObject row = command(connection, deviceId, commandId);
+            String action = row.getString("action");
+            if(!REMOTE.contains(action))
+            {
+               throw new PrintingException(409, "This action has no device receipt");
+            }
+            Set<String> outcomes = "REFRESH_INVENTORY".equals(action)
+               ? Set.of("INVENTORY_REFRESHED", "UNSUPPORTED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN")
+               : Set.of("CANCEL_REQUESTED", "ALREADY_ABSENT", "OWNERSHIP_MISMATCH", "UNSUPPORTED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN");
+            if(!outcomes.contains(outcome))
+            {
+               throw new PrintingException(400, "Invalid command outcome");
+            }
+            if(row.has("receipt_json"))
+            {
+               if(!new JSONObject(row.getString("receipt_json")).similar(receipt))
+               {
+                  throw new PrintingException(409, "Command receipt is immutable");
+               }
+            }
+            else
+            {
+               String status = switch(outcome)
+               {
+                  case "INVENTORY_REFRESHED", "CANCEL_REQUESTED", "ALREADY_ABSENT" -> "SUCCEEDED";
+                  case "EXPIRED", "OUTCOME_UNKNOWN" -> outcome;
+                  default -> "FAILED";
+               };
+               update(connection, "UPDATE printing_device_command SET status=?,receipt_json=? WHERE id=? AND tenant_id=? AND device_id=?", status, receipt.toString(), commandId, tenant, deviceId);
+            }
+            connection.commit();
+            return (new JSONObject().put("accepted", true));
+         }
+         catch(Exception exception)
+         {
+            connection.rollback();
+            throw exception;
+         }
+      }
+   }
+
+
+   /** Management history is bounded and remains readable after revocation. */
+   JSONObject page(String deviceId, int limit, String before) throws SQLException
+   {
+      if(limit < 1 || limit > 200)
+      {
+         throw new PrintingException(400, "Invalid command page limit");
+      }
+      try(Connection connection = source.getConnection())
+      {
+         List<JSONObject> rows;
+         if(query(connection, "SELECT id FROM printing_device WHERE tenant_id=? AND id=?", tenant, deviceId).isEmpty())
+         {
+            throw new PrintingException(404, "Device not found");
+         }
+         if(before == null)
+         {
+            rows = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? ORDER BY created_at DESC,id DESC LIMIT ?", tenant, deviceId, limit + 1);
+         }
+         else
+         {
+            JSONObject cursor = command(connection, deviceId, before);
+            rows = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND (created_at<? OR (created_at=? AND id<?)) ORDER BY created_at DESC,id DESC LIMIT ?", tenant, deviceId, cursor.getString("created_at"), cursor.getString("created_at"), before, limit + 1);
+         }
+         JSONArray commands = new JSONArray();
+         for(JSONObject row : rows.subList(0, Math.min(limit, rows.size())))
+         {
+            commands.put(record(row));
+         }
+         return (new JSONObject().put("commands", commands).put("nextCursor", rows.size() > limit ? rows.get(limit - 1).getString("id") : JSONObject.NULL));
+      }
+   }
+
+
+   /** Look up one exact tenant/device command without exposing another owner. */
+   JSONObject get(String deviceId, String commandId) throws SQLException
+   {
+      try(Connection connection = source.getConnection())
+      {
+         return (record(command(connection, deviceId, commandId)));
+      }
+   }
+
+
+   /** Serialize a device before any state, claim, or command mutation. */
+   private JSONObject lock(Connection connection, String deviceId, boolean active) throws SQLException
+   {
+      List<JSONObject> rows = query(connection, "SELECT * FROM printing_device WHERE tenant_id=? AND id=? FOR UPDATE", tenant, deviceId);
+      if(rows.isEmpty() || (active && (rows.getFirst().getInt("enabled") != 1 || rows.getFirst().has("revoked_at"))))
+      {
+         throw new PrintingException(404, "Device not found");
+      }
+      return (rows.getFirst());
+   }
+
+
+   /** Expiry stops delivery, but a later first receipt can still report actual execution. */
+   private void expire(Connection connection, String deviceId) throws SQLException
+   {
+      update(connection, "UPDATE printing_device_command SET status='EXPIRED' WHERE tenant_id=? AND device_id=? AND status='PENDING' AND expires_at<?", tenant, deviceId, Instant.now().toString());
+   }
+
+
+   /** Single-record lookup is always scoped, including cursors and receipts. */
+   private JSONObject command(Connection connection, String deviceId, String id) throws SQLException
+   {
+      List<JSONObject> rows = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND id=?", tenant, deviceId, id);
+      if(rows.isEmpty())
+      {
+         throw new PrintingException(404, "Command not found");
+      }
+      return (rows.getFirst());
+   }
+
+
+   /** Stable wire projection excludes raw request and authentication state. */
+   private static JSONObject record(JSONObject row)
+   {
+      JSONObject value = new JSONObject().put("commandId", row.getString("id")).put("requestId", row.getString("request_id")).put("issuedAt", new JSONObject(row.getString("request_json")).getString("issuedAt"))
+         .put("deviceId", row.getString("device_id")).put("action", row.getString("action")).put("status", row.getString("status"))
+         .put("createdAt", row.getString("created_at")).put("expiresAt", row.getString("expires_at"));
+      if("PENDING".equals(row.getString("status")) && Instant.parse(row.getString("expires_at")).isBefore(Instant.now()))
+      {
+         value.put("status", "EXPIRED");
+      }
+      if(row.has("job_id"))
+      {
+         value.put("jobId", row.getString("job_id"));
+      }
+      if(row.has("result_code"))
+      {
+         value.put("resultCode", row.getString("result_code"));
+      }
+      if(row.has("cancelled_job_count"))
+      {
+         value.put("cancelledJobCount", row.getInt("cancelled_job_count"));
+      }
+      if(row.has("receipt_json"))
+      {
+         value.put("receipt", new JSONObject(row.getString("receipt_json")));
+      }
+      return (value);
+   }
+
+
+   /** Numeric aggregates do not load a receipt history into application memory. */
+   private static long count(Connection connection, String sql, Object... values) throws SQLException
+   {
+      return (query(connection, sql, values).getFirst().getLong("n"));
+   }
+
+
+   /** Reject ambiguous or oversized text before persistence. */
+   private static String text(JSONObject object, String field, int maximum)
+   {
+      if(!(object.opt(field) instanceof String value) || value.isBlank() || value.length() > maximum || value.indexOf('\0') >= 0)
+      {
+         throw new PrintingException(400, "Invalid " + field);
+      }
+      return (value);
+   }
+
+
+   /** Protocol times have explicit UTC spelling rather than an implicit local zone. */
+   private static String utc(JSONObject object, String field)
+   {
+      String value = text(object, field, 40);
+      if(!value.endsWith("Z"))
+      {
+         throw new PrintingException(400, "UTC timestamp required");
+      }
+      return (value);
+   }
+
+   /** Require an exact nonnegative integral JSON value without coercion. */
+   private static long integer(JSONObject object, String field)
+   {
+      Object value = object.opt(field);
+      if(!(value instanceof Integer || value instanceof Long) || (((Number) value).longValue() < 0 || ((Number) value).longValue() > 9007199254740991L))
+      {
+         throw new PrintingException(400, "Invalid " + field);
+      }
+      return (((Number) value).longValue());
+   }
+
+
+   /** A closed vocabulary prevents arbitrary command payloads. */
+   private static void fields(JSONObject object, Set<String> allowed)
+   {
+      if(!allowed.containsAll(object.keySet()))
+      {
+         throw new PrintingException(400, "Unknown control field");
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingDeviceProcesses.java

@@ -0,0 +1,351 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** Native administration controls use the caller's QQQ session and selected rows.
+ ** Review is read-only; durable service requests execute only in the load step.
+ *******************************************************************************/
+public final class PrintingDeviceProcesses
+{
+   static final String REQUEST_ID = "printingControlRequestId";
+   static final String ISSUED_AT = "printingControlIssuedAt";
+   static final String CONFIRM = "confirmPrintingControl";
+
+
+
+   /***************************************************************************
+    ** Each action is associated with both record and table-selection menus.
+    ***************************************************************************/
+   public enum Action
+   {
+      PAUSE("printingPauseDevices", "Pause printing", "PAUSE_DISPATCH", false, false,
+         "New work will stop being dispatched. Jobs already received by Windows may still print."),
+      RESUME("printingResumeDevices", "Resume printing", "RESUME_DISPATCH", false, false,
+         "Dispatch will resume for connected, authorized devices. Administrative disconnect remains unchanged."),
+      DISCONNECT("printingDisconnectDevices", "Disconnect devices", "DISCONNECT", false, false,
+         "Normal printing traffic will stop. The outbound control channel remains available for reconnect."),
+      RECONNECT("printingReconnectDevices", "Reconnect devices", "RECONNECT", false, false,
+         "Connected agents will be asked to resume normal traffic. An offline computer cannot be reached immediately."),
+      REVOKE("printingRevokeDevices", "Revoke device access", "REVOKE", true, false,
+         "Access will be revoked permanently. The old credential cannot be restored; local re-enrollment is required."),
+      REFRESH("printingRefreshDevices", "Refresh printer inventory", "REFRESH_INVENTORY", false, false,
+         "A bounded refresh request will wait for a compatible agent. Acceptance does not mean it has executed."),
+      CLEAR("printingClearDeviceQueues", "Cancel queued jobs", "CLEAR_QUEUE", true, false,
+         "Only jobs still queued in QQQ will be canceled. History remains and Windows jobs are not purged."),
+      CANCEL_WINDOWS("printingCancelWindowsJobs", "Cancel Windows print job", "CANCEL_SPOOL", false, true,
+         "The agent will request cancellation only with proof that the spool entry belongs to this job. Printed output cannot be recalled.");
+
+      final String process;
+      final String label;
+      final String wire;
+      final boolean confirmation;
+      final boolean job;
+      final String preview;
+
+
+
+      /************************************************************************
+       ** Keep labels separate from the closed wire action vocabulary.
+       ************************************************************************/
+      Action(String process, String label, String wire, boolean confirmation, boolean job, String preview)
+      {
+         this.process = process;
+         this.label = label;
+         this.wire = wire;
+         this.confirmation = confirmation;
+         this.job = job;
+         this.preview = preview;
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Utility class.
+    ***************************************************************************/
+   private PrintingDeviceProcesses()
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** Standard streamed review supports checked rows, records and query selection.
+    ***************************************************************************/
+   public static void register(QInstance instance)
+   {
+      for(Action action : Action.values())
+      {
+         String table = action.job ? PrintingTables.JOB : PrintingTables.DEVICE;
+         Map<String, Serializable> values = new HashMap<>();
+         values.put(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE, table);
+         values.put(StreamedETLWithFrontendProcess.FIELD_DESTINATION_TABLE, table);
+         values.put(StreamedETLWithFrontendProcess.FIELD_SUPPORTS_FULL_VALIDATION, true);
+         values.put(StreamedETLWithFrontendProcess.FIELD_DO_FULL_VALIDATION, true);
+         values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, action.preview);
+         QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(PrintingExtract.class, Transform.class, Load.class, values)
+            .withName(action.process).withLabel(action.label).withTableName(table).withMinInputRecords(1)
+            .withPermissionRules(PrintingProcesses.permissionRules());
+         process.withStep(0, new QBackendStepMetaData().withName("prepareControl").withCode(new QCodeReference(Prepare.class)));
+         if(action.confirmation)
+         {
+            process.withStep(1, new QFrontendStepMetaData().withName("confirmControl").withLabel(action.label)
+               .withFormField(new QFieldMetaData(CONFIRM, QFieldType.BOOLEAN).withLabel("I understand and confirm this action").withDefaultValue(false))
+               .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM)));
+         }
+         instance.addProcess(process);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Unknown names must never choose a more privileged default action.
+    ***************************************************************************/
+   static Action action(RunBackendStepInput input) throws QException
+   {
+      for(Action action : Action.values())
+      {
+         if(action.process.equals(input.getProcessName()))
+         {
+            return (action);
+         }
+      }
+      throw new QException("Unknown printing control action");
+   }
+
+
+
+   /***************************************************************************
+    ** Use a real authenticated user identifier, never a client-supplied actor.
+    ***************************************************************************/
+   static String actor(RunBackendStepInput input) throws QException
+   {
+      new PrintingAdminPermission().checkPermissionsThrowing(input, null);
+      PrintingProcesses.currentService();
+      if(QContext.getQSession() == null || QContext.getQSession().getUser() == null
+         || QContext.getQSession().getUser().getIdReference() == null || QContext.getQSession().getUser().getIdReference().isBlank())
+      {
+         throw new QException("Sign in with an authorized QQQ user before controlling a print device");
+      }
+      return (QContext.getQSession().getUser().getIdReference());
+   }
+
+
+
+   /***************************************************************************
+    ** Resolve current records through QQQ permissions and tenant row locks.
+    ***************************************************************************/
+   static QRecord resolve(RunBackendStepInput input, String id) throws QException
+   {
+      Action action = action(input);
+      GetInput get = new GetInput();
+      get.setTableName(action.job ? PrintingTables.JOB : PrintingTables.DEVICE);
+      get.setPrimaryKey(id);
+      get.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
+      QRecord record = new GetAction().execute(get).getRecord();
+      if(record == null)
+      {
+         throw new QException("Choose an accessible print " + (action.job ? "job" : "device"));
+      }
+      if(action.job && "QUEUED".equals(record.getValueString("status")))
+      {
+         throw new QException("Use Cancel queued jobs for work that has not been dispatched to Windows");
+      }
+      return (record);
+   }
+
+
+
+   /***************************************************************************
+    ** Keep request identity and issue time stable throughout review and replay.
+    ***************************************************************************/
+   public static class Prepare implements BackendStep
+   {
+      /************************************************************************
+       ** No service mutation or command delivery occurs during preparation.
+       ************************************************************************/
+      @Override
+      public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         actor(input);
+         action(input);
+         String request = input.getValueString(REQUEST_ID);
+         String issued = input.getValueString(ISSUED_AT);
+         if((request == null || request.isBlank()) != (issued == null || issued.isBlank()))
+         {
+            throw new QException("Restart this action to obtain a complete control request identity");
+         }
+         output.addValue(REQUEST_ID, request == null || request.isBlank() ? UUID.randomUUID().toString() : request);
+         output.addValue(ISSUED_AT, issued == null || issued.isBlank() ? Instant.now().toString() : issued);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** The native preview rechecks scope without changing device or queue state.
+    ***************************************************************************/
+   public static class Transform extends AbstractTransformStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine ready = new ProcessSummaryLine(Status.OK, 0, null)
+         .withSingularFutureMessage("record will receive the selected control action")
+         .withPluralFutureMessage("records will receive the selected control action");
+
+
+
+      /************************************************************************
+       ** Never trust extracted rows after permissions or records have changed.
+       ************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         actor(input);
+         for(QRecord selected : input.getRecords())
+         {
+            QRecord current = resolve(input, selected.getValueString("id"));
+            ready.incrementCountAndAddPrimaryKey(current.getValue("id"));
+            output.getRecords().add(current);
+         }
+      }
+
+
+
+      /************************************************************************
+       ** Standard summary links preserve the native record/table workflow.
+       ************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         return (new ArrayList<>(List.of(ready)));
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Apply the same durable action service as the authenticated HTTP adapter.
+    ***************************************************************************/
+   public static class Load extends AbstractLoadStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine applied = new ProcessSummaryLine(Status.OK, 0, null)
+         .withSingularPastMessage("server control action was applied; device observation is shown separately")
+         .withPluralPastMessage("server control actions were applied; device observations are shown separately");
+      private final ProcessSummaryLine pending = new ProcessSummaryLine(Status.WARNING, 0, null)
+         .withSingularPastMessage("agent request is pending; no remote execution is confirmed")
+         .withPluralPastMessage("agent requests are pending; no remote execution is confirmed");
+      private final ProcessSummaryLine unresolved = new ProcessSummaryLine(Status.WARNING, 0, null)
+         .withSingularPastMessage("request did not complete; inspect command history before trying another request")
+         .withPluralPastMessage("requests did not complete; inspect command history before trying another request");
+
+
+
+      /************************************************************************
+       ** Recheck current scope and consent immediately before each mutation.
+       ************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         actor(input);
+         Action action = action(input);
+         if(action.confirmation && !Boolean.TRUE.equals(input.getValueBoolean(CONFIRM)))
+         {
+            throw new QException("Confirm the reviewed action before continuing");
+         }
+         String requestId = input.getValueString(REQUEST_ID);
+         String issuedAt = input.getValueString(ISSUED_AT);
+         if(requestId == null || requestId.isBlank() || issuedAt == null || issuedAt.isBlank())
+         {
+            throw new QException("Restart this action to obtain a stable control request identity");
+         }
+         for(QRecord selected : input.getRecords())
+         {
+            QRecord current = resolve(input, selected.getValueString("id"));
+            String deviceId = current.getValueString(action.job ? "device_id" : "id");
+            JSONObject request = new JSONObject().put("requestId", action.job ? requestId + "-" + current.getValueString("id") : requestId)
+               .put("issuedAt", issuedAt).put("action", action.wire);
+            if(action.job)
+            {
+               request.put("jobId", current.getValueString("id"));
+            }
+            try
+            {
+               JSONObject result = PrintingControlAuthorization.deviceAction(deviceId, request);
+               String status = result.getString("status");
+               ProcessSummaryLine summary = "PENDING".equals(status) ? pending : ("SUCCEEDED".equals(status) ? applied : unresolved);
+               summary.incrementCountAndAddPrimaryKey(current.getValue("id"));
+               output.getRecords().add(current);
+            }
+            catch(Exception exception)
+            {
+               throw new QException("Printing control could not be completed. Review command history before submitting a new action.", exception);
+            }
+         }
+      }
+
+
+
+      /************************************************************************
+       ** Pending requests are never presented as completed Windows operations.
+       ************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         return (new ArrayList<>(List.of(applied, pending, unresolved)));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingDeviceStatus.java

@@ -0,0 +1,179 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.time.Instant;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Presence and control application are observations, separate from desired state.
+ *******************************************************************************/
+public class PrintingDeviceStatus implements TableCustomizerInterface
+{
+   private static final Set<String> DEPENDENCIES = Set.of("id", "enabled", "connection_state", "last_seen_at", "control_last_poll_at", "dispatch_paused", "control_version", "control_revision", "control_applied_revision");
+
+
+
+   /***************************************************************************
+    ** Query/Get already applied native user permissions and tenant row security.
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postQuery(QueryOrGetInputInterface input, List<QRecord> records) throws QException
+   {
+      Set<String> selected = input instanceof QueryInput query ? query.getFieldNamesToInclude() : null;
+      if(selected != null && !selected.contains("device_status") && !selected.contains("control_status"))
+      {
+         return (records);
+      }
+      if(selected != null && !selected.contains("id"))
+      {
+         throw new QException("Select id together with derived device status fields");
+      }
+      Map<String, QRecord> dependencies = dependencies(records);
+      Instant now = Instant.now();
+      for(QRecord record : records)
+      {
+         QRecord values = dependencies.getOrDefault(record.getValueString("id"), record);
+         if(selected == null || selected.contains("device_status"))
+         {
+            record.setValue("device_status", presence(values, now));
+         }
+         if(selected == null || selected.contains("control_status"))
+         {
+            record.setValue("control_status", application(values));
+         }
+      }
+      return (records);
+   }
+
+
+
+   /***************************************************************************
+    ** Visible-column projections still need authoritative inputs. Fetch bounded
+    ** batches through the same native permissions, never raw SQL or one query
+    ** per row. Dependency-only queries do not invoke this enrichment again.
+    ***************************************************************************/
+   private static Map<String, QRecord> dependencies(List<QRecord> records) throws QException
+   {
+      ArrayList<String> ids = new ArrayList<>();
+      for(QRecord record : records)
+      {
+         if(!record.getValues().keySet().containsAll(DEPENDENCIES) && record.getValueString("id") != null)
+         {
+            ids.add(record.getValueString("id"));
+         }
+      }
+      Map<String, QRecord> result = new HashMap<>();
+      for(int first = 0; first < ids.size(); first += 200)
+      {
+         List<String> page = ids.subList(first, Math.min(first + 200, ids.size()));
+         QueryInput input = new QueryInput().withTableName(PrintingTables.DEVICE).withFieldNamesToInclude(DEPENDENCIES)
+            .withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.IN, page).withLimit(page.size()));
+         input.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
+         for(QRecord row : new QueryAction().execute(input).getRecords())
+         {
+            result.put(row.getValueString("id"), row);
+         }
+      }
+      return (result);
+   }
+
+
+
+   /***************************************************************************
+    ** A recently seen control poll still proves liveness while printing is paused.
+    ***************************************************************************/
+   static String presence(QRecord record, Instant now)
+   {
+      if(record.getValueInteger("enabled") != null && record.getValueInteger("enabled") == 0)
+      {
+         return ("REVOKED");
+      }
+      if("DISCONNECTED".equals(record.getValueString("connection_state")))
+      {
+         return ("DISCONNECTED");
+      }
+      Instant heartbeat = timestamp(record.getValueString("last_seen_at"));
+      Instant control = timestamp(record.getValueString("control_last_poll_at"));
+      Instant seen = heartbeat == null || (control != null && control.isAfter(heartbeat)) ? control : heartbeat;
+      if(seen == null || seen.isAfter(now.plusSeconds(30)))
+      {
+         return ("UNKNOWN");
+      }
+      if(seen.isBefore(now.minusSeconds(90)))
+      {
+         return ("OFFLINE");
+      }
+      return (Integer.valueOf(1).equals(record.getValueInteger("dispatch_paused")) ? "PAUSED" : "ONLINE");
+   }
+
+
+
+   /***************************************************************************
+    ** A server-side successful action is not proof that the agent applied it.
+    ***************************************************************************/
+   static String application(QRecord record)
+   {
+      if(!Integer.valueOf(1).equals(record.getValueInteger("control_version")))
+      {
+         return ("UNKNOWN");
+      }
+      Long desired = record.getValueLong("control_revision");
+      Long observed = record.getValueLong("control_applied_revision");
+      return (desired != null && observed != null && desired.equals(observed) ? "APPLIED" : "PENDING");
+   }
+
+
+
+   /***************************************************************************
+    ** Bad observations must remain unknown rather than imply a healthy device.
+    ***************************************************************************/
+   private static Instant timestamp(String value)
+   {
+      if(value == null || value.isBlank())
+      {
+         return (null);
+      }
+      try
+      {
+         return (Instant.parse(value));
+      }
+      catch(DateTimeParseException exception)
+      {
+         return (null);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStorage.java

@@ -94,15 +94,22 @@ public class PrintingDocumentStorage
     ** Bound reads even if stored content was replaced outside this service.
     ***************************************************************************/
    public byte[] get(String table, String reference) throws SQLException
+   {
+      return (get(table, reference, Math.toIntExact(PrintingRealtimePolicy.defaults().get("maxPdfBytes"))));
+   }
+
+
+   /** Internal retry callers supply the exact persisted length, independent of the current format policy. */
+   public byte[] get(String table, String reference, int maximum) throws SQLException
    {
       return (execute(() ->
       {
          try(InputStream stream = new StorageAction().getInputStream(input(table, reference)))
          {
-            byte[] bytes = stream.readNBytes(20 * 1024 * 1024 + 1);
-            if(bytes.length > 20 * 1024 * 1024)
+            byte[] bytes = stream.readNBytes(maximum);
+            if(stream.read() != -1)
             {
-               throw new PrintingException(502, "Stored print document exceeds the allowed size");
+               throw new PrintingException(502, "Stored print document exceeds its declared length");
             }
             return bytes;
          }
@@ -110,6 +117,13 @@ public class PrintingDocumentStorage
    }
 
 
+   /** Return the native backend stream; the request owns closing it and enforcing its declared length. */
+   public InputStream open(String table, String reference) throws SQLException
+   {
+      return (execute(() -> new StorageAction().getInputStream(input(table, reference))));
+   }
+
+
 
    /***************************************************************************
     ** Backend deletion is idempotent; callers mark receipts only after success.

src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStream.java

@@ -0,0 +1,90 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.io.FilterInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.HexFormat;
+
+
+/** Length and digest verification remains bounded while transferring a retained object. */
+final class PrintingDocumentStream extends FilterInputStream
+{
+   private final long length;
+   private final String expectedHash;
+   private final MessageDigest digest;
+   private long received;
+   private boolean verified;
+
+
+   /** Wrap a source with immutable document integrity metadata. */
+   PrintingDocumentStream(InputStream input, long length, String expectedHash)
+   {
+      super(input);
+      this.length = length;
+      this.expectedHash = expectedHash;
+      try
+      {
+         digest = MessageDigest.getInstance("SHA-256");
+      }
+      catch(NoSuchAlgorithmException exception)
+      {
+         throw new IllegalStateException(exception);
+      }
+   }
+
+
+   @Override
+   public int read() throws IOException
+   {
+      byte[] one = new byte[1];
+      return (read(one, 0, 1) == -1 ? -1 : Byte.toUnsignedInt(one[0]));
+   }
+
+
+   @Override
+   public int read(byte[] bytes, int offset, int count) throws IOException
+   {
+      int read = in.read(bytes, offset, (int) Math.min(count, Math.max(1, length - received + 1)));
+      if(read > 0)
+      {
+         received += read;
+         if(received > length)
+         {
+            throw new IOException("Stored print document exceeds its declared length");
+         }
+         digest.update(bytes, offset, read);
+      }
+      else if(read == -1 && !verified)
+      {
+         verified = true;
+         if(received != length || !HexFormat.of().formatHex(digest.digest()).equals(expectedHash))
+         {
+            throw new IOException("Stored print document integrity check failed");
+         }
+      }
+      return (read);
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingExtract.java

@@ -0,0 +1,56 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
+import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ExtractViaQueryStep;
+
+
+/** Printing selections enforce current native table permissions before preview or extraction. */
+public class PrintingExtract extends ExtractViaQueryStep
+{
+   /** Preserve the standard callback, then prevent it from weakening current-user enforcement. */
+   @Override
+   protected void customizeInputPreQuery(RunBackendStepInput input, QueryInput query)
+   {
+      super.customizeInputPreQuery(input, query);
+      query.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+   }
+
+
+   /** RC20 exposes no count-input hook; authorize before its unchanged tenant-filtered count. */
+   @Override
+   public Integer doCount(RunBackendStepInput input) throws QException
+   {
+      CountInput count = new CountInput();
+      count.setTableName(input.getValueString(FIELD_SOURCE_TABLE));
+      count.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      PermissionsHelper.checkTablePermissionThrowing(count, TablePermissionSubType.READ);
+      return (super.doCount(input));
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingFacilities.java

@@ -22,6 +22,7 @@ package com.kingsrook.qbits.printing;
 
 
 import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
 import com.kingsrook.qqq.backend.core.actions.values.SearchPossibleValueSourceAction;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
@@ -95,12 +96,14 @@ final class PrintingFacilities
          throw new QException("Select an available facility");
       }
       String source = QContext.getQInstance().getTable(PrintingTables.DEVICE).getField("facility_id").getPossibleValueSourceName();
-      var options = new SearchPossibleValueSourceAction().execute(new SearchPossibleValueSourceInput()
-         .withPossibleValueSourceName(source).withIdList(List.of(selected)));
+      SearchPossibleValueSourceInput input = new SearchPossibleValueSourceInput()
+         .withPossibleValueSourceName(source).withIdList(List.of(selected));
+      input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      var options = new SearchPossibleValueSourceAction().execute(input);
       if(options.getResults() == null || options.getResults().stream().noneMatch(option -> selected.equals(String.valueOf(option.getId()))))
       {
          throw new QException("The selected facility is unavailable or is not accessible to this user");
       }
       return (selected);
    }
-}
+}

src/main/java/com/kingsrook/qbits/printing/PrintingHome.java

@@ -88,6 +88,7 @@ public class PrintingHome extends AbstractWidgetRenderer
       add(instance, app, "printingHomePrinters", "Printers needing attention", WidgetType.STATISTICS, "systemHealth", 21, 3);
       add(instance, app, "printingHomeFailures", "Failed or uncertain jobs", WidgetType.STATISTICS, "systemHealth", 22, 3);
       add(instance, app, "printingHomePending", "Pending print jobs", WidgetType.STATISTICS, "systemHealth", 23, 3);
+      add(instance, app, "printingHomeControls", "Pending device commands", WidgetType.STATISTICS, "systemHealth", 24, 12);
       add(instance, app, "printingHomeWork", "Pending and recent print work", WidgetType.TABLE, "queue", 30, 12);
    }
 
@@ -127,11 +128,13 @@ public class PrintingHome extends AbstractWidgetRenderer
       QWidgetData data = switch(input.getWidgetMetaData().getName())
       {
          case "printingHomeHeader" -> header();
-         case "printingHomeAttention" -> attention(now);
-         case "printingHomeOffline" -> statistic(DEVICE, offline(now), "Devices · now · target 0 without heartbeat for 90 seconds");
+         case "printingHomeAttention" -> attention(now, freshnessSeconds());
+         case "printingHomeOffline" -> offlineStatistic(now);
          case "printingHomePrinters" -> statistic(PRINTER, printerIssues(), "Enabled printers · now · target 0 needing attention");
          case "printingHomeFailures" -> statistic(JOB, failures(now), "Jobs created in last 24 hours · target 0 failed or uncertain");
          case "printingHomePending" -> statistic(JOB, statuses(PENDING), "Jobs · now · target queue drains after printing");
+         case "printingHomeControls" -> statistic(PrintingTables.COMMAND, statuses(List.of("PENDING"))
+            .withCriteria("expires_at", QCriteriaOperator.GREATER_THAN_OR_EQUALS, now.toString()), "Device commands · now · awaiting an agent receipt; not confirmed applied");
          case "printingHomeWork" -> work(now);
          default -> throw new QException("Unknown printing home widget");
       };
@@ -150,6 +153,8 @@ public class PrintingHome extends AbstractWidgetRenderer
          .withBlock(text("Scope: current tenant. Devices/printers: now. Job exceptions/recent work: last 24 hours."))
          .withBlock(text("Enroll a print device").withLink(new BlockLink("/app/printingEnrollDevice/?returnTo=%2Fapp%2Fprinting%2F")))
          .withBlock(text("Printing retention settings").withLink(new BlockLink("/app/printingRetentionSettings/?returnTo=%2Fapp%2Fprinting%2F")))
+         .withBlock(text("Printing connection and limits").withLink(new BlockLink("/app/printingRealtimeSettings/?returnTo=%2Fapp%2Fprinting%2F")))
+         .withBlock(text("Printing queue and storage limits").withLink(new BlockLink("/app/printingAdmissionSettings/?returnTo=%2Fapp%2Fprinting%2F")))
          .withBlock(text("Run retention cleanup").withLink(new BlockLink("/app/printingRunRetention/?returnTo=%2Fapp%2Fprinting%2F")))
          .withBlock(text("Printing setup and help").withLink(new BlockLink("https://github.com/QRun-IO/qbit-printing/blob/main/docs/OPERATIONS.md")));
       if(count(DEVICE, new QQueryFilter()) == 0)
@@ -164,16 +169,30 @@ public class PrintingHome extends AbstractWidgetRenderer
    /***************************************************************************
     ** Severity order: failed work, disconnected devices, then printer issues.
     ***************************************************************************/
-   private static TableData attention(Instant now) throws QException
+   private static TableData attention(Instant now, long freshnessSeconds) throws QException
    {
       List<Map<String, Object>> rows = new ArrayList<>();
-      for(QRecord job : query(JOB, failures(now).withOrderBy(new QFilterOrderBy("created_at", true)).withLimit(10)))
+      for(QRecord job : query(JOB, failures(now).withOrderBy(new QFilterOrderBy("created_at", false)).withLimit(10)))
       {
          rows.add(issue(JOB, job, job.getValueString("title"), job.getValueString("status"), "Check the local queue and physical output before retrying an uncertain job.", "created_at"));
       }
-      for(QRecord device : query(DEVICE, offline(now).withOrderBy(new QFilterOrderBy("last_seen_at", true)).withLimit(10)))
+      for(QRecord device : query(DEVICE, offline(now, freshnessSeconds).withOrderBy(new QFilterOrderBy("last_seen_at", true)).withLimit(10)))
       {
-         rows.add(issue(DEVICE, device, device.getValueString("name"), "No heartbeat for 90 seconds", "Open the Windows agent and check its service and outbound connection.", "last_seen_at"));
+         boolean disconnected = "DISCONNECTED".equals(device.getValueString("connection_state"));
+         rows.add(issue(DEVICE, device, device.getValueString("name"), disconnected ? "Administratively disconnected" : "No connection for " + freshnessSeconds + " seconds",
+            disconnected ? "Open the device and use Reconnect; review its observed control revision." : "Open the Windows agent and check its service, sign-in and outbound connection.", "last_seen_at"));
+      }
+      for(QRecord device : query(DEVICE, new QQueryFilter().withCriteria("enabled", QCriteriaOperator.EQUALS, 1)
+         .withCriteria("dispatch_paused", QCriteriaOperator.EQUALS, 1).withOrderBy(new QFilterOrderBy("name")).withLimit(10)))
+      {
+         rows.add(issue(DEVICE, device, device.getValueString("name"), "Dispatch paused", "Open the device queue, then use Resume dispatch when it is ready.", "control_last_poll_at"));
+      }
+      for(QRecord command : query(PrintingTables.COMMAND, statuses(List.of("PENDING", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"))
+         .withCriteria("created_at", QCriteriaOperator.GREATER_THAN_OR_EQUALS, now.minusSeconds(86400).toString())
+         .withOrderBy(new QFilterOrderBy("created_at", false)).withLimit(10)))
+      {
+         rows.add(issue(PrintingTables.COMMAND, command, command.getValueString("action"), command.getValueString("command_status"),
+            "Review command history and the device connection before submitting another request.", "created_at"));
       }
       for(QRecord printer : query(PRINTER, printerIssues().withOrderBy(new QFilterOrderBy("last_seen_at", true)).withLimit(10)))
       {
@@ -225,7 +244,9 @@ public class PrintingHome extends AbstractWidgetRenderer
     ***************************************************************************/
    private static List<QRecord> query(String table, QQueryFilter filter) throws QException
    {
-      return (new QueryAction().execute(new QueryInput().withTableName(table).withFilter(filter)).getRecords());
+      QueryInput input = new QueryInput().withTableName(table).withFilter(filter);
+      input.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
+      return (new QueryAction().execute(input).getRecords());
    }
 
 
@@ -235,17 +256,61 @@ public class PrintingHome extends AbstractWidgetRenderer
     ***************************************************************************/
    private static int count(String table, QQueryFilter filter) throws QException
    {
-      return (new CountAction().execute(new CountInput(table).withFilter(filter)).getCount());
+      CountInput input = new CountInput(table).withFilter(filter);
+      input.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
+      return (new CountAction().execute(input).getCount());
    }
 
 
 
    /***************************************************************************
-    ** A heartbeat older than 90 seconds means disconnected, not printer failure.
+    ** Current tenant policy controls freshness, retaining the legacy grace period.
     ***************************************************************************/
-   private static QQueryFilter offline(Instant now)
+   private static long freshnessSeconds() throws QException
    {
-      return (new QQueryFilter().withCriteria("enabled", QCriteriaOperator.EQUALS, 1).withCriteria("last_seen_at", QCriteriaOperator.LESS_THAN, now.minusSeconds(90).toString()));
+      try
+      {
+         return (Math.max(90, PrintingProcesses.currentService().realtimePolicy().get("heartbeatTimeoutSeconds")));
+      }
+      catch(java.sql.SQLException exception)
+      {
+         throw new QException("Could not read printing connection freshness settings", exception);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Explain the exact threshold used by the linked native filter.
+    ***************************************************************************/
+   private static StatisticsData offlineStatistic(Instant now) throws QException
+   {
+      long seconds = freshnessSeconds();
+      return (statistic(DEVICE, offline(now, seconds), "Enabled devices · now · disconnected by an administrator or unseen for " + seconds + " seconds"));
+   }
+
+
+
+   /***************************************************************************
+    ** Either authenticated connection proves liveness; requested disconnect stays visible.
+    ***************************************************************************/
+   private static QQueryFilter offline(Instant now, long freshnessSeconds)
+   {
+      QQueryFilter unseen = new QQueryFilter().withSubFilter(stale("last_seen_at", now, freshnessSeconds)).withSubFilter(stale("control_last_poll_at", now, freshnessSeconds));
+      QQueryFilter disconnected = new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR)
+         .withCriteria("connection_state", QCriteriaOperator.EQUALS, "DISCONNECTED").withSubFilter(unseen);
+      return (new QQueryFilter().withCriteria("enabled", QCriteriaOperator.EQUALS, 1).withSubFilter(disconnected));
+   }
+
+
+
+   /***************************************************************************
+    ** Legacy devices may never have sent a control poll.
+    ***************************************************************************/
+   private static QQueryFilter stale(String field, Instant now, long freshnessSeconds)
+   {
+      return (new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR)
+         .withCriteria(field, QCriteriaOperator.IS_BLANK).withCriteria(field, QCriteriaOperator.LESS_THAN, now.minusSeconds(freshnessSeconds).toString()));
    }
 
 

src/main/java/com/kingsrook/qbits/printing/PrintingJobProcesses.java

@@ -49,7 +49,6 @@ import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMeta
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
-import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ExtractViaQueryStep;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
 import org.json.JSONObject;
@@ -82,7 +81,7 @@ public class PrintingJobProcesses
          values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, retry
             ? "Each selected job will create a new print job. Previously spooled or uncertain output may print twice. Inspect the printer before continuing."
             : "Only selected jobs still queued in QQQ will be canceled. Jobs already received by a device must be inspected in the Windows companion.");
-         QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(ExtractViaQueryStep.class, Transform.class, Load.class, values)
+         QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(PrintingExtract.class, Transform.class, Load.class, values)
             .withName(name).withLabel(retry ? "Print again" : "Cancel queued jobs").withTableName(PrintingTables.JOB).withMinInputRecords(1)
             .withPermissionRules(PrintingProcesses.permissionRules());
          if(retry)
@@ -124,6 +123,7 @@ public class PrintingJobProcesses
    static QRecord resolve(RunBackendStepInput input, String id) throws QException
    {
       GetInput get = new GetInput();
+      get.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
       get.setTableName(PrintingTables.JOB);
       get.setPrimaryKey(id);
       QRecord job = new GetAction().execute(get).getRecord();

src/main/java/com/kingsrook/qbits/printing/PrintingLayout.java

@@ -0,0 +1,502 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.PDPageContentStream;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.font.PDType0Font;
+
+
+/*******************************************************************************
+ ** A small monospace page writer shared by the record, table-list and text
+ ** documents: a heading on the first page, a running title on later pages,
+ ** lines that break onto new pages (optionally repeating a header), and
+ ** "Page n of m" footers. Characters the bundled font cannot encode print as ?.
+ *******************************************************************************/
+final class PrintingLayout implements AutoCloseable
+{
+   static final float MARGIN = 40;
+   static final int MAX_PAGES = 500;
+
+   private final PDDocument document = new PDDocument();
+   private final PDType0Font font;
+   private final PDRectangle size;
+   private final String title;
+   private PDPageContentStream content;
+   private float y;
+   private List<String> repeatHeader = List.of();
+   private int repeatSize = 8;
+   private PrintingChrome chrome;
+   private float leading = 1.35f;
+
+
+
+   /***************************************************************************
+    ** Page size LETTER or A4, portrait or landscape; the first page carries
+    ** the title and subtitle.
+    ***************************************************************************/
+   PrintingLayout(String pageSize, boolean landscape, String title, String subtitle) throws QException
+   {
+      this(pageSize, landscape, title, subtitle, null);
+   }
+
+
+
+   /***************************************************************************
+    ** With the app's header and footer on every page (defaults when null).
+    ***************************************************************************/
+   PrintingLayout(String pageSize, boolean landscape, String title, String subtitle, PrintingChrome chrome) throws QException
+   {
+      this.chrome = chrome == null ? PrintingChrome.defaults(title) : chrome;
+      try(InputStream stream = PrintingLayout.class.getResourceAsStream(PrintingTestDocuments.FONT_RESOURCE))
+      {
+         if(stream == null)
+         {
+            throw new IOException("Bundled document font is missing");
+         }
+         font = PDType0Font.load(document, stream, true);
+         PDRectangle base = "A4".equals(pageSize == null ? null : pageSize.toUpperCase(Locale.ROOT)) ? PDRectangle.A4 : PDRectangle.LETTER;
+         size = landscape ? new PDRectangle(base.getHeight(), base.getWidth()) : base;
+         this.title = title == null ? "" : title;
+         newPage();
+         line(this.title, 15);
+         y -= 4;
+         if(subtitle != null && !subtitle.isBlank())
+         {
+            line(subtitle, 9);
+         }
+         y -= 4;
+         rule();
+         y -= 6;
+      }
+      catch(IOException exception)
+      {
+         close();
+         throw new QException("Could not start the print document", exception);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** How many monospace characters fit across the page at a font size.
+    ***************************************************************************/
+   int columns(float fontSize)
+   {
+      return (Math.max(20, (int) ((size.getWidth() - 2 * MARGIN) / (0.6f * fontSize))));
+   }
+
+
+
+   /***************************************************************************
+    ** Line spacing as a multiple of the font size (1.35 by default; text
+    ** captures use less so box-drawing characters join up).
+    ***************************************************************************/
+   void leading(float factor)
+   {
+      leading = factor;
+   }
+
+
+
+   /***************************************************************************
+    ** A note above the footer of every page (a grid's filter and sort).
+    ***************************************************************************/
+   void footer(String text)
+   {
+      chrome = chrome.withFooterNote(text);
+   }
+
+
+
+   /***************************************************************************
+    ** Lines repeated at the top of every following page (a table header).
+    ***************************************************************************/
+   void repeatOnNewPages(List<String> lines, int fontSize)
+   {
+      repeatHeader = List.copyOf(lines);
+      repeatSize = fontSize;
+   }
+
+
+
+   /***************************************************************************
+    ** One line at a font size; breaks the page first when it does not fit.
+    ***************************************************************************/
+   void line(String text, float fontSize) throws IOException
+   {
+      float step = fontSize * leading;
+      if(y - step < bottom())
+      {
+         newPage();
+         for(String header : repeatHeader)
+         {
+            draw(header, repeatSize, repeatSize * leading);
+         }
+      }
+      draw(text, fontSize, step);
+   }
+
+
+
+   /***************************************************************************
+    ** Keep at least this many lines together (a heading with its first rows).
+    ***************************************************************************/
+   void keep(int lines, int fontSize) throws IOException
+   {
+      if(y - lines * fontSize * leading < bottom())
+      {
+         newPage();
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Vertical space.
+    ***************************************************************************/
+   void gap(float points)
+   {
+      y -= points;
+   }
+
+
+
+   /***************************************************************************
+    ** A thin rule across the page.
+    ***************************************************************************/
+   void rule() throws IOException
+   {
+      content.moveTo(MARGIN, y);
+      content.lineTo(size.getWidth() - MARGIN, y);
+      content.stroke();
+      y -= 4;
+   }
+
+
+
+   /***************************************************************************
+    ** Footers on every page, then the PDF bytes.
+    ***************************************************************************/
+   byte[] finish() throws QException
+   {
+      try
+      {
+         content.close();
+         content = null;
+         int total = document.getNumberOfPages();
+         for(int i = 0; i < total; i++)
+         {
+            PDPage page = document.getPage(i);
+            try(PDPageContentStream footer = new PDPageContentStream(document, page, PDPageContentStream.AppendMode.APPEND, true, true))
+            {
+               String text = "Page " + (i + 1) + " of " + total;
+               float base = MARGIN - 14;
+               footer.setLineWidth(0.5f);
+               footer.moveTo(MARGIN, base + (hasNote() ? 20 : 10));
+               footer.lineTo(size.getWidth() - MARGIN, base + (hasNote() ? 20 : 10));
+               footer.stroke();
+               if(hasNote())
+               {
+                  at(footer, MARGIN, base + 10, PrintingRecordDocuments.truncate(chrome.footerNote(), columns(7.5f)), 7.5f);
+               }
+               at(footer, size.getWidth() - MARGIN - text.length() * 4.8f, base, text, 8);
+               at(footer, MARGIN, base, PrintingRecordDocuments.truncate(chrome.footerLeft(), Math.max(10, columns(8) - text.length() - 2)), 8);
+            }
+         }
+         ByteArrayOutputStream output = new ByteArrayOutputStream();
+         document.save(output);
+         return (output.toByteArray());
+      }
+      catch(IOException exception)
+      {
+         throw new QException("Could not render the print document", exception);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Release the document.
+    ***************************************************************************/
+   @Override
+   public void close()
+   {
+      try
+      {
+         if(content != null)
+         {
+            content.close();
+         }
+         document.close();
+      }
+      catch(IOException exception)
+      {
+         // nothing more to release
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Start a page; later pages show the running title.
+    ***************************************************************************/
+   private void newPage() throws IOException
+   {
+      if(document.getNumberOfPages() >= MAX_PAGES)
+      {
+         throw new IOException("The document would exceed " + MAX_PAGES + " pages; print fewer rows");
+      }
+      if(content != null)
+      {
+         content.close();
+      }
+      PDPage page = new PDPage(size);
+      document.addPage(page);
+      content = new PDPageContentStream(document, page);
+      y = size.getHeight() - MARGIN + 14;
+      header();
+      if(document.getNumberOfPages() > 1)
+      {
+         draw(PrintingRecordDocuments.truncate(title, columns(8)) + " (continued)", 8, 12);
+         y -= 4;
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** The app's header band: the app and server/user/time, then the title or
+    ** breadcrumb, then a rule.
+    ***************************************************************************/
+   private void header() throws IOException
+   {
+      String right = chrome.headerRight();
+      int rightChars = Math.min(right.length(), columns(7.5f) / 2 + 10);
+      String rightText = PrintingRecordDocuments.truncate(right, rightChars);
+      y -= 9;
+      at(content, MARGIN, y, PrintingRecordDocuments.truncate(chrome.app(), Math.max(10, columns(9) - rightText.length())), 9);
+      at(content, size.getWidth() - MARGIN - rightText.length() * 4.5f, y, rightText, 7.5f);
+      if(chrome.title() != null && !chrome.title().isBlank())
+      {
+         y -= 10;
+         at(content, MARGIN, y, PrintingRecordDocuments.truncate(chrome.title(), columns(7.5f)), 7.5f);
+      }
+      y -= 4;
+      content.setLineWidth(0.5f);
+      content.moveTo(MARGIN, y);
+      content.lineTo(size.getWidth() - MARGIN, y);
+      content.stroke();
+      content.setLineWidth(1f);
+      y -= 6;
+   }
+
+
+
+   /***************************************************************************
+    ** Whether pages carry a footer note.
+    ***************************************************************************/
+   private boolean hasNote()
+   {
+      return (chrome.footerNote() != null && !chrome.footerNote().isBlank());
+   }
+
+
+
+   /***************************************************************************
+    ** The lowest baseline body text may use, above the footer band.
+    ***************************************************************************/
+   private float bottom()
+   {
+      return (MARGIN + (hasNote() ? 22 : 12));
+   }
+
+
+
+   /***************************************************************************
+    ** Text at a position on a content stream.
+    ***************************************************************************/
+   private void at(PDPageContentStream stream, float x, float baseline, String text, float fontSize) throws IOException
+   {
+      stream.beginText();
+      stream.setFont(font, fontSize);
+      stream.newLineAtOffset(x, baseline);
+      stream.showText(safe(text));
+      stream.endText();
+   }
+
+
+
+   /***************************************************************************
+    ** Draw one line at the current position.
+    ***************************************************************************/
+   private void draw(String text, float fontSize, float step) throws IOException
+   {
+      y -= step;
+      content.beginText();
+      content.setFont(font, fontSize);
+      content.newLineAtOffset(MARGIN, y);
+      content.showText(safe(PrintingRecordDocuments.truncate(text, columns(fontSize))));
+      content.endText();
+   }
+
+
+
+   /***************************************************************************
+    ** Replace characters the font cannot encode, and control characters.
+    ***************************************************************************/
+   private String safe(String text)
+   {
+      StringBuilder out = new StringBuilder();
+      text.codePoints().forEach(codePoint ->
+      {
+         String character = new String(Character.toChars(codePoint));
+         if(Character.isISOControl(codePoint))
+         {
+            out.append(' ');
+            return;
+         }
+         try
+         {
+            font.encode(character);
+            out.append(character);
+         }
+         catch(IllegalArgumentException | IOException exception)
+         {
+            out.append('?');
+         }
+      });
+      return (out.toString());
+   }
+
+
+
+   /***************************************************************************
+    ** Width-limited columns for a table: natural widths shrunk to the line.
+    ***************************************************************************/
+   static int[] columnWidths(List<String> headers, List<List<String>> rows, int available)
+   {
+      return (fit(naturalWidths(headers, rows), available));
+   }
+
+
+
+   /***************************************************************************
+    ** Each column's natural width: the header or the 90th percentile of its
+    ** cells, between 4 and 60 characters.
+    ***************************************************************************/
+   static int[] naturalWidths(List<String> headers, List<List<String>> rows)
+   {
+      int count = headers.size();
+      int[] widths = new int[count];
+      for(int c = 0; c < count; c++)
+      {
+         List<Integer> lengths = new ArrayList<>();
+         for(List<String> row : rows)
+         {
+            lengths.add(c < row.size() && row.get(c) != null ? row.get(c).length() : 0);
+         }
+         lengths.sort(null);
+         int typical = lengths.isEmpty() ? 0 : lengths.get(Math.max(0, (int) Math.ceil(lengths.size() * 0.9) - 1));
+         widths[c] = Math.max(4, Math.min(60, Math.max(headers.get(c).length(), typical)));
+      }
+      return (widths);
+   }
+
+
+
+   /***************************************************************************
+    ** The width a row of these columns takes, with two-space gaps.
+    ***************************************************************************/
+   static int lineWidth(int[] widths)
+   {
+      return (sum(widths) + Math.max(0, widths.length - 1) * 2);
+   }
+
+
+
+   /***************************************************************************
+    ** Shrink widths (widest first, never below 4) until a row fits.
+    ***************************************************************************/
+   static int[] fit(int[] start, int available)
+   {
+      int[] widths = start.clone();
+      while(lineWidth(widths) > available)
+      {
+         int widest = 0;
+         for(int c = 1; c < widths.length; c++)
+         {
+            if(widths[c] > widths[widest])
+            {
+               widest = c;
+            }
+         }
+         if(widths[widest] <= 4)
+         {
+            break;
+         }
+         widths[widest]--;
+      }
+      return (widths);
+   }
+
+
+
+   /***************************************************************************
+    ** Sum of widths.
+    ***************************************************************************/
+   private static int sum(int[] values)
+   {
+      int total = 0;
+      for(int value : values)
+      {
+         total += value;
+      }
+      return (total);
+   }
+
+
+
+   /***************************************************************************
+    ** One table row laid out in fixed-width columns.
+    ***************************************************************************/
+   static String row(List<String> cells, int[] widths)
+   {
+      StringBuilder out = new StringBuilder();
+      for(int c = 0; c < widths.length; c++)
+      {
+         String cell = c < cells.size() && cells.get(c) != null ? cells.get(c).replace('\n', ' ').replace('\r', ' ') : "";
+         cell = PrintingRecordDocuments.truncate(cell, widths[c]);
+         out.append(c == 0 ? "" : "  ").append(String.format("%-" + widths[c] + "s", cell));
+      }
+      return (out.toString().stripTrailing());
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingListProcesses.java

@@ -0,0 +1,496 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Locale;
+import java.util.UUID;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
+import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
+import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValue;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSourceType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+
+
+/*******************************************************************************
+ ** Two print processes that are not bound to one table:
+ **
+ ** - printingPrintTableList: a table list (grid) of any readable table. Values:
+ **   tableName, columns (comma separated, in order; default the visible
+ **   fields), filterJSON (a QQueryFilter with orderBys; its skip/limit are the
+ **   page), scope PAGE (the filter's skip/limit) or ALL (the whole result,
+ **   read a thousand rows at a time, up to maxRows: default and most 10,000;
+ **   a larger result prints its first rows and says so), columnWidths (the
+ **   grid's widths in characters, comma separated, same order), pageSize
+ **   LETTER/A4, orientation PORTRAIT/LANDSCAPE/AUTO (landscape when the
+ **   columns need it; the default), title, filterDescription (the filter as
+ **   the user sees it), then the printer and copies.
+ ** - printingPrintText: any text as a monospace PDF (a capture of a terminal
+ **   screen). Values: title, text, subtitle, pageSize, orientation, printer,
+ **   copies.
+ **
+ ** Both ask for the printer on an options form (prefilled from the init
+ ** values), queue one PDF job and return its id in printingJobIds. Reading the
+ ** table enforces the user's table and record permissions.
+ *******************************************************************************/
+public final class PrintingListProcesses
+{
+   public static final String TABLE_LIST = "printingPrintTableList";
+   public static final String TEXT = "printingPrintText";
+   public static final int MAX_ROWS = 10_000;
+   public static final int DEFAULT_MAX_ROWS = MAX_ROWS;
+   static final int QUERY_PAGE = 1000;
+   static final String REQUEST_ID = "printingListRequestId";
+
+
+
+   /***************************************************************************
+    ** Utility class.
+    ***************************************************************************/
+   private PrintingListProcesses()
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** Register both processes and their choice lists.
+    ***************************************************************************/
+   public static void register(QInstance instance)
+   {
+      choices(instance, "printing_pageSize", List.of("LETTER", "A4"), List.of("Letter", "A4"));
+      choices(instance, "printing_orientation", List.of("AUTO", "PORTRAIT", "LANDSCAPE"), List.of("Automatic (landscape when the columns need it)", "Portrait", "Landscape"));
+      choices(instance, "printing_listScope", List.of("ALL", "PAGE"), List.of("All rows (current filter and sort)", "The current page"));
+      instance.addProcess(process(TABLE_LIST, "Print a table list", List.of(
+         new QFieldMetaData("tableName", QFieldType.STRING).withLabel("Table").withIsRequired(true),
+         new QFieldMetaData("scope", QFieldType.STRING).withLabel("Rows").withPossibleValueSourceName("printing_listScope").withDefaultValue("ALL"),
+         new QFieldMetaData("maxRows", QFieldType.INTEGER).withLabel("Most rows (all rows)").withDefaultValue(DEFAULT_MAX_ROWS),
+         new QFieldMetaData("orientation", QFieldType.STRING).withLabel("Orientation").withPossibleValueSourceName("printing_orientation").withDefaultValue("AUTO"))));
+      instance.addProcess(process(TEXT, "Print text", List.of(
+         new QFieldMetaData("title", QFieldType.STRING).withLabel("Title"),
+         new QFieldMetaData("orientation", QFieldType.STRING).withLabel("Orientation").withPossibleValueSourceName("printing_orientation").withDefaultValue("PORTRAIT"))));
+   }
+
+
+
+   /***************************************************************************
+    ** prepare, options (printer and layout), execute, result.
+    ***************************************************************************/
+   private static QProcessMetaData process(String name, String label, List<QFieldMetaData> extra)
+   {
+      List<QFieldMetaData> fields = new ArrayList<>(extra);
+      fields.add(PrintingRecordProcesses.printerField());
+      fields.add(new QFieldMetaData(PrintingRecordProcesses.COPIES_FIELD, QFieldType.INTEGER).withLabel("Copies").withIsRequired(true).withDefaultValue(1));
+      fields.add(new QFieldMetaData("pageSize", QFieldType.STRING).withLabel("Paper").withPossibleValueSourceName("printing_pageSize").withDefaultValue("LETTER"));
+      return (new QProcessMetaData().withName(name).withLabel(label).withPermissionRules(PrintingProcesses.permissionRules())
+         .withStep(new QBackendStepMetaData().withName("prepare").withCode(new QCodeReference(Prepare.class)))
+         .withStep(new QFrontendStepMetaData().withName("options").withLabel("Choose a printer").withFormFields(fields)
+            .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM)))
+         .withStep(new QBackendStepMetaData().withName("execute").withCode(new QCodeReference(Execute.class)))
+         .withStep(new QFrontendStepMetaData().withName("result").withLabel("Result")
+            .withViewFields(List.of(new QFieldMetaData("result", QFieldType.STRING).withLabel("Result")))
+            .withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM))));
+   }
+
+
+
+   /***************************************************************************
+    ** A fixed enum choice list.
+    ***************************************************************************/
+   private static void choices(QInstance instance, String name, List<String> ids, List<String> labels)
+   {
+      ArrayList<QPossibleValue<?>> values = new ArrayList<>();
+      for(int i = 0; i < ids.size(); i++)
+      {
+         values.add(new QPossibleValue<>(ids.get(i), labels.get(i)));
+      }
+      instance.addPossibleValueSource(new QPossibleValueSource().withName(name).withType(QPossibleValueSourceType.ENUM).withEnumValues(values));
+   }
+
+
+
+   /***************************************************************************
+    ** The table a table list reads, checked readable.
+    ***************************************************************************/
+   static QTableMetaData table(RunBackendStepInput input) throws QException
+   {
+      String name = input.getValueString("tableName");
+      QTableMetaData table = name == null ? null : QContext.getQInstance().getTable(name);
+      if(table == null)
+      {
+         throw new QException("Choose a table to print (unknown table " + name + ")");
+      }
+      PrintingTableSettings settings = PrintingTableSettings.of(table);
+      if(settings != null && !settings.getPrintable())
+      {
+         throw new QException(table.getLabel() + " is not printable");
+      }
+      return (table);
+   }
+
+
+
+   /***************************************************************************
+    ** The filter from filterJSON (or everything), with the page or the row limit.
+    ***************************************************************************/
+   static QQueryFilter filter(RunBackendStepInput input) throws QException
+   {
+      String json = input.getValueString("filterJSON");
+      QQueryFilter filter;
+      try
+      {
+         filter = json == null || json.isBlank() ? new QQueryFilter() : JsonUtils.toObject(json, QQueryFilter.class);
+      }
+      catch(Exception exception)
+      {
+         throw new QException("The filter is not valid: " + exception.getMessage(), exception);
+      }
+      if("ALL".equalsIgnoreCase(input.getValueString("scope")))
+      {
+         Integer max = input.getValueInteger("maxRows");
+         int limit = max == null ? DEFAULT_MAX_ROWS : max;
+         if(limit < 1 || limit > MAX_ROWS)
+         {
+            throw new QException("Most rows must be between 1 and " + MAX_ROWS);
+         }
+         filter.setSkip(0);
+         filter.setLimit(limit);
+      }
+      else
+      {
+         if(filter.getLimit() == null || filter.getLimit() > MAX_ROWS)
+         {
+            filter.setLimit(filter.getLimit() == null ? 50 : MAX_ROWS);
+         }
+      }
+      return (filter);
+   }
+
+
+
+   /***************************************************************************
+    ** The columns to print: given (unknown names refused), else visible fields.
+    ***************************************************************************/
+   static List<QFieldMetaData> columns(QTableMetaData table, String given) throws QException
+   {
+      List<QFieldMetaData> out = new ArrayList<>();
+      if(given == null || given.isBlank())
+      {
+         table.getFields().values().stream().filter(PrintingRecordProcesses::printable).forEach(out::add);
+         return (out);
+      }
+      for(String name : Arrays.stream(given.split(",")).map(String::trim).filter(n -> !n.isEmpty()).toList())
+      {
+         QFieldMetaData field = table.getFields().get(name);
+         if(field == null)
+         {
+            throw new QException("Table " + table.getName() + " has no field " + name);
+         }
+         if(PrintingRecordProcesses.printable(field))
+         {
+            out.add(field);
+         }
+      }
+      if(out.isEmpty())
+      {
+         throw new QException("None of the columns can be printed");
+      }
+      return (out);
+   }
+
+
+
+   /***************************************************************************
+    ** The rows to print: the page as given, or the whole result read a page at
+    ** a time up to the filter's limit (the print limit).
+    ***************************************************************************/
+   static List<QRecord> read(QTableMetaData table, QQueryFilter filter, boolean all) throws QException
+   {
+      List<QRecord> out = new ArrayList<>();
+      int limit = filter.getLimit() == null ? 50 : filter.getLimit();
+      int skip = filter.getSkip() == null ? 0 : filter.getSkip();
+      while(out.size() < limit)
+      {
+         int size = all ? Math.min(QUERY_PAGE, limit - out.size()) : limit;
+         QueryInput query = new QueryInput();
+         query.setTableName(table.getName());
+         query.setFilter(filter.clone().withSkip(skip + out.size()).withLimit(size));
+         query.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+         query.setShouldGenerateDisplayValues(true);
+         query.setShouldTranslatePossibleValues(true);
+         List<QRecord> page = new QueryAction().execute(query).getRecords();
+         out.addAll(page);
+         if(!all || page.size() < size)
+         {
+            break;
+         }
+      }
+      return (out);
+   }
+
+
+
+   /***************************************************************************
+    ** The sort as labels: "Last name, First name descending".
+    ***************************************************************************/
+   static String sortText(QTableMetaData table, QQueryFilter filter)
+   {
+      if(filter.getOrderBys() == null)
+      {
+         return ("");
+      }
+      List<String> parts = new ArrayList<>();
+      for(var orderBy : filter.getOrderBys())
+      {
+         String name = orderBy.getFieldName();
+         QFieldMetaData field = name == null ? null : table.getFields().get(name);
+         parts.add((field == null || field.getLabel() == null ? name : field.getLabel()) + (orderBy.getIsAscending() ? "" : " descending"));
+      }
+      return (String.join(", ", parts));
+   }
+
+
+
+   /***************************************************************************
+    ** The grid's column widths ("12,30,8"), or null.
+    ***************************************************************************/
+   static int[] widths(String text)
+   {
+      if(text == null || text.isBlank())
+      {
+         return (null);
+      }
+      try
+      {
+         return (Arrays.stream(text.split(",")).map(String::trim).mapToInt(Integer::parseInt).toArray());
+      }
+      catch(NumberFormatException exception)
+      {
+         return (null);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** AUTO unless PORTRAIT or LANDSCAPE was chosen.
+    ***************************************************************************/
+   static String orientation(RunBackendStepInput input)
+   {
+      String value = input.getValueString("orientation");
+      return (value == null || value.isBlank() ? "AUTO" : value.toUpperCase(Locale.ROOT));
+   }
+
+
+
+   /***************************************************************************
+    ** A rendered document: its title, the PDF, and a note (rows left out).
+    ***************************************************************************/
+   public record Rendered(String title, byte[] bytes, String message)
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** Render a table list (list true) or a text page from the process values.
+    ***************************************************************************/
+   static Rendered render(RunBackendStepInput input, boolean list) throws QException
+   {
+      String pageSize = input.getValueString("pageSize") == null ? "LETTER" : input.getValueString("pageSize").toUpperCase(Locale.ROOT);
+      if(!list)
+      {
+         String title = input.getValueString("title") == null || input.getValueString("title").isBlank() ? "Screen" : input.getValueString("title");
+         String subtitle = input.getValueString("subtitle");
+         boolean landscape = "LANDSCAPE".equalsIgnoreCase(input.getValueString("orientation"));
+         PrintingChrome chrome = PrintingChrome.from(input, title);
+         String sections = input.getValueString("sections");
+         if(sections != null && !sections.isBlank())
+         {
+            return (new Rendered(title, PrintingTextDocuments.sectionsPdf(title, subtitle, sections(sections), pageSize, landscape, chrome), null));
+         }
+         return (new Rendered(title, PrintingTextDocuments.pdf(title, subtitle, input.getValueString("text"), pageSize, landscape, chrome), null));
+      }
+      QTableMetaData table = table(input);
+      List<QFieldMetaData> columns = columns(table, input.getValueString("columns"));
+      QQueryFilter filter = filter(input);
+      boolean all = "ALL".equalsIgnoreCase(input.getValueString("scope"));
+      List<QRecord> records = read(table, filter, all);
+      List<List<String>> rows = new ArrayList<>();
+      for(QRecord record : records)
+      {
+         List<String> row = new ArrayList<>();
+         columns.forEach(field -> row.add(PrintingRecordProcesses.text(record, field)));
+         rows.add(row);
+      }
+      String title = input.getValueString("title") != null ? input.getValueString("title") : table.getLabel();
+      Integer total = input.getValueInteger("printingRowCount");
+      if(total == null)
+      {
+         CountInput count = new CountInput();
+         count.setTableName(table.getName());
+         count.setFilter(filter.clone().withSkip(null).withLimit(null));
+         count.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+         total = new CountAction().execute(count).getCount();
+      }
+      int skip = filter.getSkip() == null ? 0 : filter.getSkip();
+      String scope = all ? (total != null && total > records.size() ? "first " + records.size() + " of " + total + " rows (print limit " + filter.getLimit() + ")" : "all " + records.size() + " rows")
+         : "rows " + (records.isEmpty() ? 0 : skip + 1) + "-" + (skip + records.size()) + (total != null ? " of " + total : "");
+      String described = input.getValueString("filterDescription");
+      String sort = sortText(table, filter);
+      String subtitle = scope + " - " + (described != null && !described.isBlank() ? "filter " + described : "no filter") + (sort.isEmpty() ? "" : " - sort " + sort);
+      String note = (described != null && !described.isBlank() ? "Filter: " + described : "No filter") + (sort.isEmpty() ? "" : " - sort: " + sort);
+      byte[] bytes = PrintingTableDocuments.pdf(title, subtitle, note,
+         columns.stream().map(field -> field.getLabel() == null ? field.getName() : field.getLabel()).toList(), rows, widths(input.getValueString("columnWidths")), pageSize, orientation(input),
+         PrintingChrome.from(input, table.getLabel() == null ? table.getName() : table.getLabel()));
+      String message = all && total != null && total > records.size()
+         ? "Printed the first " + records.size() + " of " + total + " rows: the print limit is " + filter.getLimit() + " rows. Narrow the filter to print the rest." : null;
+      return (new Rendered(title, bytes, message));
+   }
+
+
+
+   /***************************************************************************
+    ** The "sections" value: a JSON array of {title, lines: [..]} (at most 500
+    ** sections), as clients send a screen's content.
+    ***************************************************************************/
+   static List<PrintingTextDocuments.Section> sections(String json) throws QException
+   {
+      try
+      {
+         org.json.JSONArray array = new org.json.JSONArray(json);
+         if(array.length() > 500)
+         {
+            throw new QException("Too many sections to print (at most 500)");
+         }
+         List<PrintingTextDocuments.Section> out = new ArrayList<>();
+         for(int i = 0; i < array.length(); i++)
+         {
+            org.json.JSONObject section = array.getJSONObject(i);
+            List<String> lines = new ArrayList<>();
+            org.json.JSONArray given = section.optJSONArray("lines");
+            for(int j = 0; given != null && j < given.length(); j++)
+            {
+               lines.add(given.optString(j, ""));
+            }
+            out.add(new PrintingTextDocuments.Section(section.optString("title", ""), lines));
+         }
+         return (out);
+      }
+      catch(org.json.JSONException exception)
+      {
+         throw new QException("The sections are not valid: " + exception.getMessage(), exception);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Request identity, and for a table list the number of rows it would print.
+    ***************************************************************************/
+   public static class Prepare implements BackendStep
+   {
+      /***************************************************************************
+       ** Check access early so the form is not shown to someone who may not print.
+       ***************************************************************************/
+      @Override
+      public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         new PrintingAdminPermission().checkPermissionsThrowing(input, null);
+         PrintingProcesses.currentService();
+         String request = input.getValueString(REQUEST_ID);
+         output.addValue(REQUEST_ID, request == null || request.isBlank() ? UUID.randomUUID().toString() : request);
+         if(TABLE_LIST.equals(input.getProcessName()))
+         {
+            QTableMetaData table = table(input);
+            CountInput count = new CountInput();
+            count.setTableName(table.getName());
+            count.setFilter(filter(input).clone().withSkip(null).withLimit(null));
+            count.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+            output.addValue("printingRowCount", new CountAction().execute(count).getCount());
+            if(input.getValueString("title") == null)
+            {
+               output.addValue("title", table.getLabel() == null ? table.getName() : table.getLabel());
+            }
+         }
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Render and queue.
+    ***************************************************************************/
+   public static class Execute implements BackendStep
+   {
+      /***************************************************************************
+       ** One PDF job on the chosen printer.
+       ***************************************************************************/
+      @Override
+      public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         new PrintingAdminPermission().checkPermissionsThrowing(input, null);
+         QRecord printer = PrintingRecordProcesses.printer(input);
+         int copies = PrintingRecordProcesses.copies(input);
+         String request = input.getValueString(REQUEST_ID);
+         if(request == null || request.isBlank())
+         {
+            throw new QException("Restart the print to obtain a safe request identity");
+         }
+         Rendered rendered = render(input, TABLE_LIST.equals(input.getProcessName()));
+         if(rendered.message() != null)
+         {
+            output.addValue("printingTruncated", true);
+            output.addValue("printingMessage", rendered.message());
+         }
+         String title = rendered.title();
+         byte[] bytes = rendered.bytes();
+         String job = PrintingRecordProcesses.queue(printer, title, bytes, copies, "list-print:" + request + ":" + input.getProcessName() + ":" + printer.getValueString("id"));
+         output.addValue(PrintingRecordProcesses.JOB_IDS, job);
+         output.addValue("result", "Queued print job " + job + ". Check Print jobs for its status." + (output.getValue("printingMessage") != null ? " " + output.getValue("printingMessage") : ""));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingLocalHost.java

@@ -132,13 +132,23 @@ public class PrintingLocalHost extends AbstractQQQApplication
     ***************************************************************************/
    void configure(QApplicationJavalinServer server, boolean frontend)
    {
+      long uploadBodyLimit;
+      try
+      {
+         PrintingRealtimePolicy policy = service.realtimePolicy();
+         uploadBodyLimit = ((Math.max(policy.get("maxPdfBytes"), policy.get("maxZplBytes")) + 2) / 3) * 4 + 65536;
+      }
+      catch(java.sql.SQLException exception)
+      {
+         throw new IllegalStateException("Cannot load printing transport limits", exception);
+      }
       PrintingRoutes routes = new PrintingRoutes(service, context -> MessageDigest.isEqual(
-         settings.administratorToken().getBytes(StandardCharsets.UTF_8), PrintingRoutes.bearer(context).getBytes(StandardCharsets.UTF_8)));
+         settings.administratorToken().getBytes(StandardCharsets.UTF_8), PrintingRoutes.bearer(context).getBytes(StandardCharsets.UTF_8)), PrintingRoutes.LegacyEnrollment.DISABLED);
       server.withPort(settings.port()).withServeFrontendNext(frontend).withServeFrontendMaterialDashboard(false)
-         .withAdditionalRouteProviders(List.of(routes)).withJavalinConfigCustomizer(config ->
+         .withAdditionalRouteProviders(List.of(routes, new PrintingRealtimeRoutes(service))).withJavalinConfigCustomizer(config ->
          {
             config.jetty.host = "127.0.0.1";
-            config.http.maxRequestSize = 29 * 1024 * 1024;
+            config.http.maxRequestSize = uploadBodyLimit;
             config.routes.before(PrintingLocalHost::guardOrigin);
          });
    }

src/main/java/com/kingsrook/qbits/printing/PrintingMediaProfile.java

@@ -0,0 +1,162 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.util.HashSet;
+import java.util.Set;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** Immutable reported Windows queue defaults; these never change printer stock.
+ *******************************************************************************/
+public record PrintingMediaProfile(String id, String revision, String name, int widthMicrons, int heightMicrons, int dpiX, int dpiY)
+{
+   /***************************************************************************
+    ** Validate the bounded wire record without coercion or guessed dimensions.
+    ***************************************************************************/
+   public static PrintingMediaProfile parse(JSONObject value)
+   {
+      if(!value.keySet().containsAll(Set.of("id", "revision", "name", "widthMicrons", "heightMicrons", "dpiX", "dpiY", "source", "applyMode"))
+         || !"WINDOWS_QUEUE_DEFAULT".equals(value.opt("source")) || !"DRIVER_DEFAULT".equals(value.opt("applyMode")))
+      {
+         throw new PrintingException(400, "Invalid reported media profile");
+      }
+      String id = text(value, "id", 128);
+      String revision = text(value, "revision", 64);
+      if(!id.matches("[A-Za-z0-9._-]+") || !revision.matches("[0-9a-f]{64}"))
+      {
+         throw new PrintingException(400, "Invalid media profile identity");
+      }
+      return new PrintingMediaProfile(id, revision, text(value, "name", 512), integer(value, "widthMicrons", 2000000),
+         integer(value, "heightMicrons", 2000000), integer(value, "dpiX", 9600), integer(value, "dpiY", 9600));
+   }
+
+
+   /***************************************************************************
+    ** Canonical public facts are separate from the immutable job selection.
+    ***************************************************************************/
+   public JSONObject json()
+   {
+      return new JSONObject().put("id", id).put("revision", revision).put("name", name).put("widthMicrons", widthMicrons)
+         .put("heightMicrons", heightMicrons).put("dpiX", dpiX).put("dpiY", dpiY)
+         .put("source", "WINDOWS_QUEUE_DEFAULT").put("applyMode", "DRIVER_DEFAULT");
+   }
+
+
+   /***************************************************************************
+    ** Missing inventory facts mean no known stock, including older clients.
+    ***************************************************************************/
+   static JSONArray inventory(JSONObject printer)
+   {
+      JSONArray values = printer.has("mediaProfiles") ? printer.optJSONArray("mediaProfiles") : new JSONArray();
+      if(values == null || values.length() > 32)
+      {
+         throw new PrintingException(400, "Invalid media profile list");
+      }
+      Set<String> ids = new HashSet<>();
+      JSONArray result = new JSONArray();
+      for(Object item : values)
+      {
+         if(!(item instanceof JSONObject object))
+         {
+            throw new PrintingException(400, "Invalid media profile");
+         }
+         PrintingMediaProfile profile = parse(object);
+         if(!ids.add(profile.id()))
+         {
+            throw new PrintingException(400, "Duplicate media profile identity");
+         }
+         result.put(profile.json());
+      }
+      return result;
+   }
+
+
+   /***************************************************************************
+    ** Validate a selection independently before comparing it with current facts.
+    ***************************************************************************/
+   static void selection(JSONObject options)
+   {
+      if(!options.has("mediaProfile"))
+      {
+         return;
+      }
+      JSONObject selected = options.optJSONObject("mediaProfile");
+      if(selected == null || !selected.keySet().equals(Set.of("id", "revision"))
+         || !text(selected, "id", 128).matches("[A-Za-z0-9._-]+") || !text(selected, "revision", 64).matches("[0-9a-f]{64}"))
+      {
+         throw new PrintingException(400, "Invalid media profile selection");
+      }
+   }
+
+
+   /***************************************************************************
+    ** Reject changed defaults before admission or document storage writes.
+    ***************************************************************************/
+   static void requireCurrent(JSONObject printer, JSONObject options)
+   {
+      if(!options.has("mediaProfile"))
+      {
+         return;
+      }
+      JSONObject selected = options.getJSONObject("mediaProfile");
+      JSONArray profiles = new JSONArray(printer.optString("media_profiles_json", "[]"));
+      for(Object item : profiles)
+      {
+         PrintingMediaProfile profile = parse((JSONObject) item);
+         if(profile.id().equals(selected.getString("id")) && profile.revision().equals(selected.getString("revision")))
+         {
+            return;
+         }
+      }
+      throw new PrintingException(409, "Printer media changed or is unavailable; select the current queue default again");
+   }
+
+
+   /***************************************************************************
+    ** Text identities and labels retain their exact value.
+    ***************************************************************************/
+   private static String text(JSONObject value, String key, int maximum)
+   {
+      if(!(value.opt(key) instanceof String text) || text.isBlank() || text.length() > maximum)
+      {
+         throw new PrintingException(400, "Invalid media profile " + key);
+      }
+      return text;
+   }
+
+
+   /***************************************************************************
+    ** Accept integral JSON values only, within the supported physical bounds.
+    ***************************************************************************/
+   private static int integer(JSONObject value, String key, int maximum)
+   {
+      Object raw = value.opt(key);
+      if(!(raw instanceof Integer || raw instanceof Long) || ((Number) raw).longValue() < 1 || ((Number) raw).longValue() > maximum)
+      {
+         throw new PrintingException(400, "Invalid media profile " + key);
+      }
+      return ((Number) raw).intValue();
+   }
+}

src/main/java/com/kingsrook/qbits/printing/PrintingOperatorAuthorization.java

@@ -0,0 +1,395 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.printing;
+
+
+import java.io.Serializable;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
+import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.model.session.QUser;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** Current-user catalog and submission boundary shared by HTTP and host processes.
+ *******************************************************************************/
+public final class PrintingOperatorAuthorization
+{
+   /***************************************************************************
+    ** No cached user authority or alternate queue.
+    ***************************************************************************/
+   private PrintingOperatorAuthorization()
+   {
+   }
+
+
+   /***************************************************************************
+    ** Resolve the authenticated actor and current tenant before every operation.
+    ***************************************************************************/
+   public static String principal() throws QException
+   {
+      if(QContext.getQSession() == null || QContext.getQSession().getUser() == null
+         || QContext.getQSession().getUser().getIdReference() == null || QContext.getQSession().getUser().getIdReference().isBlank())
+      {
+         throw new QAuthenticationException("Sign in to continue");
+      }
+      new PrintingOperatorPermission().checkPermissionsThrowing(new RunBackendStepInput(), null);
+      PrintingProcesses.currentService();
+      return QContext.getQSession().getUser().getIdReference();
+   }
+
+
+   /***************************************************************************
+    ** Native table and record checks apply even inside another backend process.
+    ***************************************************************************/
+   private static QRecord record(String table, String id) throws QException
+   {
+      CallContext caller = capture();
+      QueryInput scoped = new QueryInput().withTableName(table).withFilter(new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.EQUALS, id))
+         .withCriteria(new QFilterCriteria("tenant_id", QCriteriaOperator.EQUALS, PrintingProcesses.currentService().getTenantId())).withLimit(1));
+      scoped.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      if(new QueryAction().execute(scoped).getRecords().isEmpty())
+      {
+         throw new QPermissionDeniedException("Print destination is not accessible");
+      }
+      caller.check();
+      GetInput input = new GetInput();
+      input.setTableName(table);
+      input.setPrimaryKey(id);
+      input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      QRecord row = new GetAction().execute(input).getRecord();
+      PermissionsHelper.checkTablePermissionThrowing(input, TablePermissionSubType.READ);
+      caller.check();
+      if(row == null || !id.equals(row.getValueString("id")))
+      {
+         throw new QPermissionDeniedException("Print destination is not accessible");
+      }
+      return row;
+   }
+
+
+   /***************************************************************************
+    ** Authorize the exact native printer row and its enabled device each time.
+    ** Callers use the returned wire printer identity only for this operation.
+    ***************************************************************************/
+   public static QRecord destination(String printerRowId) throws QException
+   {
+      CallContext caller = capture();
+      QRecord printer = record(PrintingTables.PRINTER, printerRowId);
+      QRecord device = record(PrintingTables.DEVICE, printer.getValueString("device_id"));
+      if(!Integer.valueOf(1).equals(printer.getValueInteger("enabled")) || !Integer.valueOf(1).equals(printer.getValueInteger("available"))
+         || !Integer.valueOf(1).equals(device.getValueInteger("enabled")))
+      {
+         throw new QPermissionDeniedException("Print destination is not approved and exposed");
+      }
+      requireDestinationRead();
+      caller.check();
+      return printer;
+   }
+
+
+   /***************************************************************************
+    ** Shared retained-source boundary also requires the exact supported format.
+    ***************************************************************************/
+   public static QRecord printer(String printerRowId, String format) throws QException
+   {
+      QRecord printer = destination(printerRowId);
+      if(!Set.of("PDF", "ZPL").contains(format) || !new JSONArray(printer.getValueString("formats")).toList().contains(format))
+      {
+         throw new PrintingException(400, "Printer does not support this document format");
+      }
+      return printer;
+   }
+
+
+   /***************************************************************************
+    ** Reconciliation still checks current row authority after exposure changes.
+    ** The caller must first establish its own accepted request/source binding.
+    ***************************************************************************/
+   public static QRecord authorizeDestinationHistory(String printerRowId) throws QException
+   {
+      CallContext caller = capture();
+      QRecord printer = record(PrintingTables.PRINTER, printerRowId);
+      record(PrintingTables.DEVICE, printer.getValueString("device_id"));
+      requireDestinationRead();
+      caller.check();
+      return printer;
+   }
+
+
+   /***************************************************************************
+    ** Page through authorized rows; hidden parent devices never leak through joins.
+    ***************************************************************************/
+   public static JSONObject catalog(int limit, String after) throws QException
+   {
+      CallContext caller = capture();
+      if(limit < 1 || limit > 200 || (after != null && !after.matches("[A-Za-z0-9._-]{1,200}")))
+      {
+         throw new PrintingException(400, "Invalid catalog page");
+      }
+      QQueryFilter filter = new QQueryFilter(new QFilterCriteria("enabled", QCriteriaOperator.EQUALS, 1))
+         .withCriteria(new QFilterCriteria("available", QCriteriaOperator.EQUALS, 1))
+         .withCriteria(new QFilterCriteria("tenant_id", QCriteriaOperator.EQUALS, PrintingProcesses.currentService().getTenantId()))
+         .withOrderBy(new QFilterOrderBy("id", true)).withLimit(limit + 1);
+      if(after != null)
+      {
+         filter.withCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, after));
+      }
+      QueryInput input = new QueryInput().withTableName(PrintingTables.PRINTER).withFilter(filter);
+      input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      List<QRecord> rows = new QueryAction().execute(input).getRecords();
+      caller.check();
+      JSONArray printers = new JSONArray();
+      int consumed = Math.min(limit, rows.size());
+      for(QRecord candidate : rows.subList(0, consumed))
+      {
+         try
+         {
+            QRecord printer = destination(candidate.getValueString("id"));
+            QRecord device = record(PrintingTables.DEVICE, printer.getValueString("device_id"));
+            requireDestinationRead();
+            caller.check();
+            printers.put(new JSONObject().put("printerRowId", printer.getValueString("id")).put("deviceId", printer.getValueString("device_id"))
+               .put("printerId", printer.getValueString("printer_id")).put("name", label(printer, "display_name", "name", "queue_name", "id"))
+               .put("deviceName", label(device, "display_name", "name", "computer_name", "id")).put("description", printer.getValueString("description")).put("location", printer.getValueString("location"))
+               .put("status", printer.getValueString("status")).put("formats", new JSONArray(printer.getValueString("formats")))
+               .put("mediaProfiles", new JSONArray(printer.getValueString("media_profiles_json") == null ? "[]" : printer.getValueString("media_profiles_json"))));
+         }
+         catch(QPermissionDeniedException hidden)
+         {
+            // Native parent-row security can legitimately hide a candidate.
+         }
+         caller.check();
+      }
+      caller.check();
+      return new JSONObject().put("printers", printers)
+         .put("nextCursor", rows.size() > limit ? rows.get(consumed - 1).getValueString("id") : JSONObject.NULL);
+   }
+
+
+   /***************************************************************************
+    ** The process permission remains authoritative for all byte submissions.
+    ***************************************************************************/
+   public static JSONObject submit(JSONObject request) throws Exception
+   {
+      CallContext caller = capture();
+      requireSubmission();
+      request = new JSONObject(request.toString());
+      if(!Set.of("requestId", "printerRowId", "title", "format", "contentBase64", "options").containsAll(request.keySet()))
+      {
+         throw new PrintingException(400, "Unknown operator print request field");
+      }
+      QRecord printer = printer(request.getString("printerRowId"), request.getString("format"));
+      caller.check();
+      JSONObject prepared = new JSONObject(request.toString());
+      prepared.put("deviceId", printer.getValueString("device_id")).put("printerId", printer.getValueString("printer_id"))
+         .put("idempotencyKey", requestKey(caller.actor(), request.getString("requestId")));
+      try
+      {
+         return caller.service().submitAuthorized(prepared, request.getString("printerRowId"), () ->
+         {
+            caller.check();
+            requireSubmission();
+            QRecord current = printer(prepared.getString("printerRowId"), prepared.getString("format"));
+            if(!prepared.getString("deviceId").equals(current.getValueString("device_id")) || !prepared.getString("printerId").equals(current.getValueString("printer_id")))
+            {
+               throw new QPermissionDeniedException("Print destination changed during submission");
+            }
+            requireSubmission();
+            caller.check();
+         });
+      }
+      catch(java.sql.SQLException exception)
+      {
+         if(exception.getCause() instanceof QException denied)
+         {
+            throw denied;
+         }
+         throw exception;
+      }
+   }
+
+
+   /***************************************************************************
+    ** Only the current actor's exact request can be reconciled; no job enumeration.
+    ***************************************************************************/
+   public static JSONObject observe(String requestId) throws Exception
+   {
+      CallContext caller = capture();
+      requireStorage(false);
+      PrintingService.OperatorAcceptance accepted = caller.service().findOperatorAcceptance(requestKey(caller.actor(), requestId));
+      if(accepted == null)
+      {
+         throw new PrintingException(404, "Print request not found");
+      }
+      JSONObject job = accepted.job();
+      // Historical acceptance remains observable if exposure changes, but current row authority is mandatory.
+      QRecord printer = authorizeDestinationHistory(accepted.printerRowId());
+      if(!job.getString("deviceId").equals(printer.getValueString("device_id")) || !job.getString("printerId").equals(printer.getValueString("printer_id")))
+      {
+         throw new QPermissionDeniedException("Accepted print destination changed");
+      }
+      requireDestinationRead();
+      requireStorage(false);
+      caller.check();
+      return job;
+   }
+
+
+   /** Recheck table, credential and channel permissions after both row customizers. */
+   private static void requireDestinationRead() throws QException
+   {
+      for(String table : List.of(PrintingTables.PRINTER, PrintingTables.DEVICE))
+      {
+         GetInput input = new GetInput();
+         input.setTableName(table);
+         input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+         PermissionsHelper.checkTablePermissionThrowing(input, TablePermissionSubType.READ);
+      }
+   }
+
+
+   /***************************************************************************
+    ** Snapshot only authority and routing context, never session credentials.
+    ***************************************************************************/
+   private static CallContext capture() throws QException
+   {
+      String actor = principal();
+      QSession session = QContext.getQSession();
+      Map<String, List<Serializable>> keys = new HashMap<>();
+      if(session.getSecurityKeyValues() != null)
+      {
+         session.getSecurityKeyValues().forEach((key, values) -> keys.put(key, values == null ? null : new ArrayList<>(values)));
+      }
+      return new CallContext(QContext.getQInstance(), session, session.getUser(), actor, PrintingProcesses.currentService(), keys,
+         session.getBackendVariants() == null ? null : new HashMap<>(session.getBackendVariants()));
+   }
+
+
+   /***************************************************************************
+    ** Native customizers cannot replace the caller or its row-security scope.
+    ** Permissions and credential/channel ceilings are separately checked live.
+    ***************************************************************************/
+   private record CallContext(QInstance instance, QSession session, QUser user, String actor, PrintingService service,
+      Map<String, List<Serializable>> keys, Map<String, Serializable> variants)
+   {
+      /** Fail before consuming callback results under a different native authority. */
+      void check() throws QException
+      {
+         if(instance != QContext.getQInstance() || session != QContext.getQSession() || user != session.getUser()
+            || !actor.equals(principal()) || service != PrintingProcesses.currentService()
+            || !keys.equals(session.getSecurityKeyValues() == null ? Map.of() : session.getSecurityKeyValues())
+            || !Objects.equals(variants, session.getBackendVariants()))
+         {
+            throw new QPermissionDeniedException("Printing authority changed during the operation");
+         }
+      }
+   }
+
+
+   /***************************************************************************
+    ** Trusted domain writes retain process, credential and channel ceilings.
+    ***************************************************************************/
+   public static void requireSubmission() throws QException
+   {
+      principal();
+      PermissionsHelper.checkProcessPermissionThrowing(new RunBackendStepInput().withProcessName(PrintingOperatorProcesses.SUBMIT), PrintingOperatorProcesses.SUBMIT);
+      requireStorage(true);
+   }
+
+
+   /***************************************************************************
+    ** Scope ceilings do not grant generic job table reads or writes.
+    ***************************************************************************/
+   private static void requireStorage(boolean mutation) throws QException
+   {
+      var instance = QContext.getQInstance();
+      var table = instance.getTable(PrintingTables.JOB);
+      if(table == null)
+      {
+         throw new QException("Printing job metadata is unavailable");
+      }
+      var rules = PermissionsHelper.getEffectivePermissionRules(table, instance);
+      if(PermissionsHelper.isDeniedForClientChannel(table, rules)
+         || (mutation && PermissionsHelper.isWriteDeniedForClientChannel(table, rules))
+         || PermissionsHelper.isOutsideCredentialScope(table, mutation ? TablePermissionSubType.INSERT : TablePermissionSubType.READ))
+      {
+         throw new QPermissionDeniedException("Current credential or client channel cannot access print acceptance");
+      }
+   }
+
+
+   /***************************************************************************
+    ** Stable actor namespace protects request lookup without storing user credentials.
+    ***************************************************************************/
+   private static String requestKey(String actor, String requestId) throws Exception
+   {
+      if(!requestId.matches("[A-Za-z0-9._:-]{1,128}"))
+      {
+         throw new PrintingException(400, "Invalid print request identity");
+      }
+      return "operator:" + HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(actor.getBytes(StandardCharsets.UTF_8))) + ":" + requestId;
+   }
+
+
+   /***************************************************************************
+    ** Legacy unnamed rows retain an honest identity fallback, never guessed media.
+    ***************************************************************************/
+   private static String label(QRecord record, String... fields)
+   {
+      for(String field : fields)
+      {
+         String value = record.getValueString(field);
+         if(value != null && !value.isBlank())
+         {
+            return value;
+         }
+      }
+      throw new PrintingException(409, "Print destination has no stable identity");
+   }
+}