Bump version to 0.6.0-SNAPSHOT [skip ci]

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/workflows/build.yaml

@@ -0,0 +1,7 @@
+name: build
+on:
+  push:
+jobs:
+  maven:
+    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/maven.yaml@v1
+    secrets: inherit

.gitea/workflows/qrun-release.yaml

@@ -1,22 +0,0 @@
-# Standard QRun release caller (v2, thin contract): every push and manual dispatch delegates to the protected qrun-release-v1 channel. Do not edit per repository.
-name: qrun-release
-on:
-  push: {}
-  workflow_dispatch: {}
-permissions:
-  contents: read
-  actions: read
-jobs:
-  release:
-    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/java-maven.yaml@qrun-release-v1
-    with:
-      runner: linux-small
-  postpublish:
-    if: ${{ needs.release.outputs.capture == 'true' }}
-    needs: release
-    permissions:
-      contents: write
-      actions: write
-    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/qrun-source-version.yaml@qrun-release-v1
-    with:
-      runner: linux-small

AGENTS.md

@@ -1,6 +1,6 @@
 # QQQ Mobile Scanners
 
-This is an application QBit and a separate local demo, using Java 21 and QQQ 4.1.0-RC.21. Optional `examples/echo` (scan-to-print) uses released Printing 1.0.0; its Generation, Record Files and Scripting owner inputs are not yet public. Contract versions: UI API 1.10, `mobile-scanners` 1.5, `printing` 2.3, `mobile-record-files` 1.0.
+This is an application QBit and a separate local demo, using Java 21 and QQQ 4.1.0-RC.21. Optional `examples/echo` (scan-to-print) uses released Printing 1.0.0; its Generation, Record Files and Scripting owner inputs are not yet public. Contract versions: UI API 1.10, `mobile-scanners` 1.6 (1.5 on the maintained local server), `printing` 2.3, `mobile-record-files` 1.0.
 The Android host is maintained in [QRun-IO/qqq-android on Gitea](https://git.kof22.com/QRun-IO/qqq-android) (reviews pulls/8 and pulls/10 are merged into `main`). Present status is in `docs/SESSION-STATE.md`; older logs are in `docs/history/`.
 
 ## Build and verify

README.md

@@ -52,7 +52,8 @@ Android host --(/qqq/v1 + mobile-scanners extension)--> QQQ server + this qbit -
 
 ## Project layout
 
-- `src/main`, `src/test`: the reusable qbit (enrollment routes, approval/revocation, scan process, table metadata) and its H2 behavior and permission tests.
+- `pom.xml`: the `qbit-mobile-scanners-reactor` aggregator (packaging pom, single `<revision>` source) of the two published modules, `base` and `integrations/record-files`; `demo` and `examples/echo` are not part of it. One root `mvn deploy` publishes the reactor POM, `qbit-mobile-scanners` and `qbit-mobile-scanners-record-files` at the same version.
+- `base/src/main`, `base/src/test`: the reusable qbit (enrollment routes, approval/revocation, scan process, table metadata) and its H2 behavior and permission tests.
 - `demo`: basic local QQQ server with persistent H2 storage, native administration UI and password login. QQQ `4.0.0` lacks the password session exchange it needs.
 - `e2e`: browser acceptance tests against the packaged frontend and an isolated real demo server.
 - `examples/echo` and `examples/echo/demo`: the optional Echo library and its runnable composed server.

base/pom.xml

@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="utf-8"?>
+<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.qbits</groupId>
+      <artifactId>qbit-mobile-scanners-reactor</artifactId>
+      <version>${revision}</version>
+      <relativePath>../pom.xml</relativePath>
+   </parent>
+   <groupId>com.kingsrook.qbits</groupId>
+   <artifactId>qbit-mobile-scanners</artifactId>
+   <version>${revision}</version>
+   <name>QQQ Mobile Scanners</name>
+   <description>Approved mobile devices and native QQQ barcode capture processes.</description>
+   <url>https://git.kof22.com/QRun-IO/qbit-mobile-scanners</url>
+   <scm>
+      <connection>scm:git:https://git.kof22.com/QRun-IO/qbit-mobile-scanners.git</connection>
+      <developerConnection>scm:git:ssh://git@git.kof22.com:22/QRun-IO/qbit-mobile-scanners.git</developerConnection>
+      <url>https://git.kof22.com/QRun-IO/qbit-mobile-scanners</url>
+      <tag>HEAD</tag>
+   </scm>
+   <issueManagement>
+      <system>Gitea</system>
+      <url>https://git.kof22.com/QRun-IO/qbit-mobile-scanners/issues</url>
+   </issueManagement>
+   <licenses>
+      <license>
+         <name>Apache License, Version 2.0</name>
+         <url>https://www.apache.org/licenses/LICENSE-2.0</url>
+         <distribution>repo</distribution>
+      </license>
+   </licenses>
+   <dependencyManagement>
+      <dependencies>
+         <dependency>
+            <groupId>com.kingsrook.qqq</groupId>
+            <artifactId>qqq-bom-pom</artifactId>
+            <version>${qqq.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+         </dependency>
+      </dependencies>
+   </dependencyManagement>
+   <dependencies>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-core</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-javalin</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-module-rdbms</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.h2database</groupId>
+         <artifactId>h2</artifactId>
+         <version>2.2.224</version>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-module-postgres</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.testcontainers</groupId>
+         <artifactId>postgresql</artifactId>
+         <version>1.21.4</version>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.postgresql</groupId>
+         <artifactId>postgresql</artifactId>
+         <version>42.7.14</version>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.junit.jupiter</groupId>
+         <artifactId>junit-jupiter</artifactId>
+         <version>5.11.4</version>
+         <scope>test</scope>
+      </dependency>
+   </dependencies>
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-checkstyle-plugin</artifactId>
+            <version>3.6.0</version>
+            <dependencies>
+               <dependency>
+                  <groupId>com.puppycrawl.tools</groupId>
+                  <artifactId>checkstyle</artifactId>
+                  <version>14.3.0</version>
+               </dependency>
+            </dependencies>
+            <configuration>
+               <configLocation>${maven.multiModuleProjectDirectory}/checkstyle/checkstyle.xml</configLocation>
+               <consoleOutput>true</consoleOutput>
+               <includeTestSourceDirectory>true</includeTestSourceDirectory>
+               <failOnViolation>true</failOnViolation>
+               <violationSeverity>warning</violationSeverity>
+            </configuration>
+            <executions>
+               <execution>
+                  <id>checkstyle</id>
+                  <phase>validate</phase>
+                  <goals>
+                     <goal>check</goal>
+                  </goals>
+               </execution>
+            </executions>
+         </plugin>
+      </plugins>
+   </build>
+</project>

base/src/main/java/com/kingsrook/qbits/mobilescanners/MobileDeviceActivity.java

@@ -69,11 +69,13 @@ final class MobileDeviceActivity
 
 
    /***************************************************************************
-    ** Preserve last known coordinates with explicit availability and timestamps.
+    ** Preserve last known coordinates with explicit availability and timestamps,
+    ** and refresh reported software versions in the same presence write.
     ***************************************************************************/
-   static void heartbeat(String id, Map<String, Object> input, boolean foreground) throws QException
+   static void heartbeat(QRecord device, Map<String, Object> input, boolean foreground) throws QException
    {
-      QRecord changes = new QRecord().withValue("id", id).withValue("lastSeenAt", Instant.now());
+      QRecord changes = new QRecord().withValue("id", device.getValueString("id")).withValue("lastSeenAt", Instant.now());
+      MobileService.refreshDeviceInfo(device, input, changes);
       String status = MobileService.optional(input, "locationStatus", 30);
       if(status != null && !List.of("AVAILABLE", "PERMISSION_DENIED", "DISABLED", "UNAVAILABLE").contains(status))
       {

base/src/main/java/com/kingsrook/qbits/mobilescanners/MobileScannersUiApi.java

@@ -46,7 +46,7 @@ public final class MobileScannersUiApi
     ***************************************************************************/
    public static MiddlewareSpecExtension extension()
    {
-      return new MiddlewareSpecExtension().withName("mobile-scanners").withSemanticVersion("1.5.0")
+      return new MiddlewareSpecExtension().withName("mobile-scanners").withSemanticVersion("1.6.0")
          .withDescription("Native scanner devices, customer branding and SCANNER process widget contract.")
          .withSpec(MobileBrandingSpec.class).withSpec(MobileStatusSpec.class)
          .withSpec(MobileEnrollSpec.class).withSpec(MobileCurrentDeviceSpec.class)

base/src/main/java/com/kingsrook/qbits/mobilescanners/MobileService.java

@@ -44,6 +44,7 @@ public final class MobileService
 {
    static final ThreadLocal<QBackendTransaction> TRANSACTION = new ThreadLocal<>();
 
+   static final List<String> DEVICE_INFO_FIELDS = List.of("manufacturer", "model", "osVersion", "appVersion");
    static final int AIM_IDENTIFIER_LENGTH = 3;
    static final int RAW_DATA_MAXIMUM_BYTES = 8192;
    static final int RAW_DATA_MAXIMUM_CHARACTERS = 10924;
@@ -78,7 +79,8 @@ public final class MobileService
       QRecord credential = new QRecord().withValue("id", id).withValue("tokenHash", hash(token));
       QRecord device = new QRecord().withValue("id", id).withValue("installationId", id).withValue("status", "PENDING")
          .withValue("enrolledBy", userId()).withValue("enrolledAt", Instant.now());
-      for(String name : new String[] { "displayName", "manufacturer", "model", "osVersion", "appVersion" })
+      device.setValue("displayName", optional(input, "displayName", 200));
+      for(String name : DEVICE_INFO_FIELDS)
       {
          device.setValue(name, optional(input, name, 200));
       }
@@ -567,6 +569,25 @@ public final class MobileService
 
 
 
+   /***************************************************************************
+    ** An updated app or OS reports new versions after enrollment; copy only
+    ** changed, bounded values so scans record the software that produced them.
+    ** Absent, null or blank values never erase what enrollment recorded.
+    ***************************************************************************/
+   static void refreshDeviceInfo(QRecord device, Map<String, ?> input, QRecord changes) throws QException
+   {
+      for(String name : DEVICE_INFO_FIELDS)
+      {
+         String value = optional(input, name, 200);
+         if(value != null && !value.isBlank() && !value.equals(device.getValueString(name)))
+         {
+            changes.setValue(name, value);
+         }
+      }
+   }
+
+
+
    /***************************************************************************
     ** Enforce canonical UUIDs before using them as identifiers.
     ***************************************************************************/

base/src/main/java/com/kingsrook/qbits/mobilescanners/MobileSessionHeartbeatSpec.java

@@ -24,7 +24,7 @@ public class MobileSessionHeartbeatSpec extends MobileDeviceJsonSpec
    {
       return new BasicOperation().withHttpMethod(HttpMethod.POST).withPath(MobileScannersUiApi.PREFIX + "/sessions/heartbeat")
          .withOperationId("mobileScannersSessionHeartbeat").withShortSummary("Report current handheld session activity")
-         .withLongDescription("Binds the current QQQ sign-in to the verified device. Nullable display metadata never grants permissions. Ended sign-ins return 401 and cannot start another mobile session. screenAvailable=false immediately removes the retained frame. Lease duration is expiresAt minus serverTime, not the device clock.");
+         .withLongDescription("Binds the current QQQ sign-in to the verified device. Nullable display metadata never grants permissions. Ended sign-ins return 401 and cannot start another mobile session. screenAvailable=false immediately removes the retained frame. Lease duration is expiresAt minus serverTime, not the device clock. Optional manufacturer, model, osVersion and appVersion refresh the enrolled device record when they differ (1.6); scans recorded afterwards carry the refreshed values.");
    }
 
 

base/src/main/java/com/kingsrook/qbits/mobilescanners/MobileSessionSchemas.java

@@ -52,10 +52,14 @@ final class MobileSessionSchemas
       activity.put("traceId", nullableText(100));
       activity.put("locationStatus", text(30).withEnumValues(List.of("AVAILABLE", "PERMISSION_DENIED", "DISABLED", "UNAVAILABLE")));
       activity.put("location", ref("MobileScannersLocationV1").withNullable(true));
+      for(String field : MobileService.DEVICE_INFO_FIELDS)
+      {
+         activity.put(field, text(200));
+      }
       schemas.put("MobileScannersLocationV1", object("Optional foreground observation with runtime permission. Coordinates are last known, not a guarantee of current position; the server separately records receipt time.", Map.of(
          "latitude", new BoundedIntegerSchema(-90, 90).withType(Type.NUMBER), "longitude", new BoundedIntegerSchema(-180, 180).withType(Type.NUMBER),
          "accuracyMeters", new BoundedIntegerSchema(0, 10000000).withType(Type.NUMBER), "capturedAt", timestamp()), "latitude", "longitude", "accuracyMeters", "capturedAt"));
-      schemas.put("MobileScannersHeartbeatRequestV1", object("Display activity only. Never include form values, barcodes, passwords or raw error messages. JSON maximum 4096 bytes. Omitted captureMode means APP_CONTENT, requiring foreground eligible app pixels. DEVICE_SCREEN requires explicit per-session Android operator consent and may remain available in background. False screenAvailable clears pixels and lease; changing mode invalidates old demand.", activity, "foreground", "screenAvailable"));
+      schemas.put("MobileScannersHeartbeatRequestV1", object("Display activity only. Never include form values, barcodes, passwords or raw error messages. JSON maximum 4096 bytes. Omitted captureMode means APP_CONTENT, requiring foreground eligible app pixels. DEVICE_SCREEN requires explicit per-session Android operator consent and may remain available in background. False screenAvailable clears pixels and lease; changing mode invalidates old demand. Optional manufacturer, model, osVersion and appVersion (1.6) refresh the enrolled device record when they differ, so later scans carry the installed software; omitted or blank values leave stored values unchanged.", activity, "foreground", "screenAvailable"));
       schemas.put("MobileScannersScreenLeaseV1", object("Server-authorized capture demand. Compute remaining duration from expiresAt minus heartbeat serverTime. Sequence is scoped to this lease and resumes at nextSequence after client restart.", Map.of(
          "leaseId", uuid(), "expiresAt", timestamp(), "frameIntervalMillis", integer(1000, 1000), "maxWidth", integer(640, 640),
          "maxHeight", integer(1280, 1280), "maxBytes", integer(262144, 262144), "nextSequence", integer(0, 9007199254740990L), "captureMode", captureMode()),

base/src/main/java/com/kingsrook/qbits/mobilescanners/MobileSessionService.java

@@ -153,7 +153,7 @@ final class MobileSessionService
       String deviceId = currentDevice();
       synchronized(current())
       {
-         MobileService.requireApproved(deviceId);
+         QRecord device = MobileService.requireApproved(deviceId);
          QRecord session = observe(deviceId);
          boolean foreground = bool(input, "foreground");
          MobileCaptureMode mode = MobileCaptureMode.parse(input.get("captureMode"));
@@ -173,7 +173,7 @@ final class MobileSessionService
             changes.setValue(name, MobileService.optional(input, name, 80));
          }
          changes.setValue("traceId", MobileService.optional(input, "traceId", 100));
-         MobileDeviceActivity.heartbeat(deviceId, input, foreground);
+         MobileDeviceActivity.heartbeat(device, input, foreground);
          update(changes);
          String id = session.getValueString("id");
          if(!available)

base/src/main/resources/openapi/qqq-v1/mobile-scanners.yaml

@@ -170,12 +170,18 @@ components:
         \ APP_CONTENT, requiring foreground eligible app pixels. DEVICE_SCREEN requires\
         \ explicit per-session Android operator consent and may remain available in\
         \ background. False screenAvailable clears pixels and lease; changing mode\
-        \ invalidates old demand."
+        \ invalidates old demand. Optional manufacturer, model, osVersion and appVersion\
+        \ (1.6) refresh the enrolled device record when they differ, so later scans\
+        \ carry the installed software; omitted or blank values leave stored values\
+        \ unchanged."
       properties:
         appName:
           maxLength: 200
           nullable: true
           type: "string"
+        appVersion:
+          maxLength: 200
+          type: "string"
         captureBlockedReason:
           maxLength: 80
           nullable: true
@@ -207,6 +213,15 @@ components:
           - "UNAVAILABLE"
           maxLength: 30
           type: "string"
+        manufacturer:
+          maxLength: 200
+          type: "string"
+        model:
+          maxLength: 200
+          type: "string"
+        osVersion:
+          maxLength: 200
+          type: "string"
         processInstanceId:
           maxLength: 200
           nullable: true
@@ -686,7 +701,7 @@ info:
   description: "Native scanner devices, customer branding and SCANNER process widget\
     \ contract."
   title: "QQQ Middleware API extension: mobile-scanners"
-  version: "1.5.0"
+  version: "1.6.0"
 openapi: "3.0.3"
 paths:
   /qqq/v1/qbit/mobile-scanners/branding:
@@ -967,7 +982,9 @@ paths:
         \ display metadata never grants permissions. Ended sign-ins return 401 and\
         \ cannot start another mobile session. screenAvailable=false immediately removes\
         \ the retained frame. Lease duration is expiresAt minus serverTime, not the\
-        \ device clock."
+        \ device clock. Optional manufacturer, model, osVersion and appVersion refresh\
+        \ the enrolled device record when they differ (1.6); scans recorded afterwards\
+        \ carry the refreshed values."
       operationId: "mobileScannersSessionHeartbeat"
       parameters:
       - description: "Enrolled installation UUID"

base/src/test/java/com/kingsrook/qbits/mobilescanners/MobileScannersApiContractTest.java

@@ -64,11 +64,19 @@ class MobileScannersApiContractTest
          assertTrue(model.getComponents().getSchemas().containsKey(schema), schema);
       }
       assertEquals(7, extension.getSpecs().size());
-      assertEquals("1.5.0", extension.getSemanticVersion());
-      assertEquals(java.util.List.of(), UiApiContract.check(generated, Files.readString(contract), Files.readString(Path.of("src/test/resources/openapi/mobile-scanners-1.4.0.yaml")), 1,
-         "Regenerate the current extension contract."));
-      assertEquals(java.util.List.of(), UiApiContract.check(generated, Files.readString(contract), Files.readString(Path.of("src/test/resources/openapi/mobile-scanners-1.5.0.yaml")), 1,
-         "Regenerate the current extension contract."));
+      assertEquals("1.6.0", extension.getSemanticVersion());
+      for(String previous : java.util.List.of("1.4.0", "1.5.0", "1.6.0"))
+      {
+         assertEquals(java.util.List.of(), UiApiContract.check(generated, Files.readString(contract), Files.readString(Path.of("src/test/resources/openapi/mobile-scanners-" + previous + ".yaml")), 1,
+            "Regenerate the current extension contract."));
+      }
+      var heartbeatRequest = model.getComponents().getSchemas().get("MobileScannersHeartbeatRequestV1");
+      for(String optional : MobileService.DEVICE_INFO_FIELDS)
+      {
+         assertTrue(heartbeatRequest.getProperties().containsKey(optional), optional);
+         assertEquals(200, heartbeatRequest.getProperties().get(optional).getMaxLength(), optional);
+         assertFalse(generated.contains("- \"" + optional + "\""), optional + " must stay optional, never a required key.");
+      }
       var scanEvent = model.getComponents().getSchemas().get("MobileScannersScanEventV1");
       var scanContext = model.getComponents().getSchemas().get("MobileScannersScanContextV1");
       for(String optional : java.util.List.of("aimIdentifier", "rawDataBase64"))

base/src/test/java/com/kingsrook/qbits/mobilescanners/MobileScannersTest.java

@@ -26,6 +26,7 @@ import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
 import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QBadRequestException;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
@@ -942,6 +943,93 @@ class MobileScannersTest
 
 
 
+   /***************************************************************************
+    ** Enrollment records the installed software; heartbeats without versions,
+    ** or with blank ones, leave it unchanged and scans copy it.
+    ***************************************************************************/
+   @Test
+   void enrollmentStoresVersionsAndHeartbeatWithoutThemLeavesThemUnchanged() throws Exception
+   {
+      String device = approvedDevice(Map.of("osVersion", "14", "appVersion", "1.0.0"));
+      QRecord enrolled = MobileService.get(MobileScannersQBitProducer.DEVICE, device);
+      assertEquals("Zebra", enrolled.getValueString("manufacturer"));
+      assertEquals("TC22", enrolled.getValueString("model"));
+      assertEquals("14", enrolled.getValueString("osVersion"));
+      assertEquals("1.0.0", enrolled.getValueString("appVersion"));
+      bind(device);
+      MobileSessionService.heartbeat(Map.of("foreground", true, "screenAvailable", false));
+      MobileSessionService.heartbeat(new HashMap<>(Map.of("foreground", true, "screenAvailable", false, "appVersion", "", "osVersion", " ")));
+      QRecord unchanged = MobileService.get(MobileScannersQBitProducer.DEVICE, device);
+      for(String field : MobileService.DEVICE_INFO_FIELDS)
+      {
+         assertEquals(enrolled.getValueString(field), unchanged.getValueString(field), field);
+      }
+      QRecord scan = MobileService.capture(scan());
+      assertEquals("1.0.0", scan.getValueString("appVersion"));
+      assertEquals("14", scan.getValueString("osVersion"));
+      assertEquals("Zebra", scan.getValueString("manufacturer"));
+      assertEquals("TC22", scan.getValueString("model"));
+   }
+
+
+
+   /***************************************************************************
+    ** An in-place app update reports its new version on the next heartbeat and
+    ** every later scan carries it; earlier scans keep the version that made them.
+    ***************************************************************************/
+   @Test
+   void heartbeatRefreshesDeviceVersionsForLaterScans() throws Exception
+   {
+      String device = approvedDevice(Map.of("osVersion", "14", "appVersion", "1.0.0"));
+      bind(device);
+      QRecord before = MobileService.capture(scan());
+      assertEquals("1.0.0", before.getValueString("appVersion"));
+      MobileSessionService.heartbeat(Map.of("foreground", true, "screenAvailable", false, "appVersion", "1.0.1", "osVersion", "15"));
+      QRecord updated = MobileService.get(MobileScannersQBitProducer.DEVICE, device);
+      assertEquals("1.0.1", updated.getValueString("appVersion"));
+      assertEquals("15", updated.getValueString("osVersion"));
+      assertEquals("Zebra", updated.getValueString("manufacturer"));
+      assertEquals("TC22", updated.getValueString("model"));
+      assertEquals("APPROVED", updated.getValueString("status"));
+      QRecord after = MobileService.capture(scan());
+      assertEquals("1.0.1", after.getValueString("appVersion"));
+      assertEquals("15", after.getValueString("osVersion"));
+      assertEquals("1.0.0", MobileService.get(MobileScannersQBitProducer.SCAN, before.getValueString("id")).getValueString("appVersion"));
+      MobileSessionService.heartbeat(Map.of("foreground", true, "screenAvailable", false, "manufacturer", "Zebra Technologies", "model", "MC9400"));
+      QRecord hardware = MobileService.get(MobileScannersQBitProducer.DEVICE, device);
+      assertEquals("Zebra Technologies", hardware.getValueString("manufacturer"));
+      assertEquals("MC9400", hardware.getValueString("model"));
+      assertEquals("1.0.1", hardware.getValueString("appVersion"));
+      assertEquals("MC9400", MobileService.capture(scan()).getValueString("model"));
+   }
+
+
+
+   /***************************************************************************
+    ** Heartbeat versions obey the enrollment limits: strings of at most 200
+    ** characters; anything else is a 400 and the device record is untouched.
+    ***************************************************************************/
+   @Test
+   void heartbeatRejectsInvalidDeviceVersionsLikeEnrollment() throws Exception
+   {
+      String tooLong = "v".repeat(201);
+      String longest = "v".repeat(200);
+      assertThrows(QBadRequestException.class, () -> MobileService.enroll(Map.of("installationId", UUID.randomUUID().toString(), "appVersion", tooLong)));
+      String device = approvedDevice(Map.of("osVersion", "14", "appVersion", "1.0.0"));
+      bind(device);
+      assertThrows(QBadRequestException.class, () -> MobileSessionService.heartbeat(Map.of("foreground", true, "screenAvailable", false, "appVersion", tooLong)));
+      assertThrows(QBadRequestException.class, () -> MobileSessionService.heartbeat(Map.of("foreground", true, "screenAvailable", false, "osVersion", 15)));
+      QRecord unchanged = MobileService.get(MobileScannersQBitProducer.DEVICE, device);
+      assertEquals("1.0.0", unchanged.getValueString("appVersion"));
+      assertEquals("14", unchanged.getValueString("osVersion"));
+      assertEquals("1.0.0", MobileService.capture(scan()).getValueString("appVersion"));
+      MobileSessionService.heartbeat(Map.of("foreground", true, "screenAvailable", false, "appVersion", longest));
+      assertEquals(longest, MobileService.get(MobileScannersQBitProducer.DEVICE, device).getValueString("appVersion"));
+      assertEquals(longest, MobileService.capture(scan()).getValueString("appVersion"));
+   }
+
+
+
    /***************************************************************************
     ** A realistic installation, with no hardware identifier requirement.
     ***************************************************************************/
@@ -1163,7 +1251,19 @@ class MobileScannersTest
     ***************************************************************************/
    private String approvedDevice() throws QException
    {
-      String id = (String) enroll().get("deviceId");
+      return approvedDevice(Map.of());
+   }
+
+
+
+   /***************************************************************************
+    ** Approve an enrollment that also reported its software versions.
+    ***************************************************************************/
+   private String approvedDevice(Map<String, Object> versions) throws QException
+   {
+      Map<String, Object> enrollment = new HashMap<>(Map.of("installationId", UUID.randomUUID().toString(), "displayName", "Test TC22", "manufacturer", "Zebra", "model", "TC22"));
+      enrollment.putAll(versions);
+      String id = (String) MobileService.enroll(enrollment).get("deviceId");
       QContext.init(instance, admin);
       MobileService.setApproval(id, true);
       QContext.init(instance, scanner);

demo/pom.xml

@@ -7,7 +7,7 @@
    <properties>
       <maven.compiler.release>21</maven.compiler.release>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-      <qqq.version>4.1.0-RC.21</qqq.version>
+      <qqq.version>4.1.0-RC.26</qqq.version>
    </properties>
    <dependencyManagement>
       <dependencies>
@@ -34,7 +34,7 @@
       <dependency>
          <groupId>com.kingsrook.qqq</groupId>
          <artifactId>qqq-frontend-next</artifactId>
-         <version>1.0.0-RC.35</version>
+         <version>1.0.0-RC.38</version>
       </dependency>
       <dependency>
          <groupId>com.h2database</groupId>
@@ -78,7 +78,7 @@
          <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-surefire-plugin</artifactId>
-            <version>3.5.2</version>
+            <version>3.5.6</version>
             <configuration>
                <systemPropertyVariables>
                   <qqq.logger.logSessionId.disabled>true</qqq.logger.logSessionId.disabled>

demo/src/test/java/com/kingsrook/qbits/mobilescanners/demo/MobileHttpAcceptanceTest.java

@@ -773,7 +773,7 @@ class MobileHttpAcceptanceTest
          }
       }
       assertNotNull(mobile);
-      assertEquals("1.5.0", mobile.getString("version"));
+      assertEquals("1.6.0", mobile.getString("version"));
       assertEquals("/qbit/mobile-scanners", mobile.getString("pathPrefix"));
       var openApiResponse = request("GET", "/qqq/v1/openapi.json", null, null, device);
       assertEquals(200, openApiResponse.statusCode());

docs/OPERATIONS.md

@@ -1,6 +1,6 @@
 # Single-instance deployment and recovery
 
-Written 2026-11-05 from the static final review of source base `a9eae04` (see [review reconciliation](REVIEW-RECONCILIATION-2026-11-05.md)). This is a **procedure**, not evidence. **No backup, restore or failover drill has been executed**, and no production storage or high-availability deployment is claimed. Nothing here adds a distributed product; the supported model is one server process per database.
+Written 2026-11-05 from the static final review of source base `a9eae04` (see [review reconciliation](REVIEW-RECONCILIATION-2026-11-05.md)). The procedure below is for the host/operator in a real incident. The only executed evidence is the automated [isolated local-demo recovery acceptance](#isolated-local-demo-recovery-acceptance-automated-passed), which covers the demo's stopped H2 database plus object snapshot and restore. No production storage, enterprise object-store or high-availability deployment is supported or qualified, and those are not tasks of this scanner release. The supported model is one server process per database.
 
 ## Topology
 
@@ -21,6 +21,22 @@ Written 2026-11-05 from the static final review of source base `a9eae04` (see [r
   6. **Echo:** jobs accepted after the snapshot may be absent from the database although a print was already queued. Manually reconcile the physical or Printing queue against the restored jobs **before authorizing any retry**, and retry only what that comparison shows was not printed. This is a manual check; there is **no exactly-once physical print guarantee**, and a retry can still produce a duplicate or a missing print if the queue or printer state is unknown.
   7. Reopen to users only after the above are done.
 
+### Isolated local-demo recovery acceptance (automated, passed)
+
+`EchoDemoAcceptanceTest.restoredSnapshotKeepsScanAndRetainedFileAndRevertedApprovalStateIsReaudited` (Echo composed demo) exercises this procedure on private temporary directories only.
+
+**Verification (2026-11-05):** the combined five-module `verify` on the merged source (`develop` `9e8685f` plus the storage fixes) passed with qualified private owner dependencies: 196 tests (root 53, demo 8, Record Files 22, Echo 74, Echo demo 39), 0 failures, 0 errors, 0 skips, and zero Checkstyle violations in every module. The qualified owner inputs are private, so this is not public-dependency qualification.
+
+The case restores H2 scan rows, the exact leading-zero value and symbology, and the Record Files owner's own `RecordFilesTables.FILE` row. It asserts that row's exact table, record and attachment relationship and the SHA-256 of the object bytes. It shows that a revocation and session end made after the snapshot are reverted by the restore, then reapplies the normal Revoke and End Session processes and shows that a valid in-flight run and a new initialization are denied. No physical printer, service or demo data was changed.
+
+Flow: it enrolls and approves a synthetic device, scans over real HTTP, and lets the real Record Files service retain the generated original in the demo local-file adapter. With the servers stopped and H2 shut down, it copies the database and object directory together, makes later changes (a second scan and file, a revocation and an ended session), restores only those two temporary directories and reads them without the application. It then restarts on a new ephemeral loopback port and applies the existing Revoke and End Session processes.
+
+What this is **not**: it covers the local demo's H2 database and local files only, using private coherent fixture inputs. It is not published-cohort qualification (that is repeated when the final public dependencies are adopted), and enterprise object-store and high-availability recovery are unsupported and unqualified. In a real incident the full procedure above still requires an operator-owned audit of approvals, sessions and the print queue before a restored service returns to users.
+
+Storage regressions in `PrivateObjectFilesTest` (part of the Echo demo's 39 tests): `concurrentSameKeyWritersLeaveOneWinnersBytesAndMetadata` (concurrent same-key writers leave one winner's bytes and metadata), `dotBucketsAreRefusedAndValidBucketsStillWork` (`.` and `..` buckets refused), plus `existingObjectIsNeverReplaced` and `keysCannotTraverseOrAlias`.
+
+Limits: the file store is the single-host demo adapter and the database is the demo's H2 file, so this does not qualify production storage, an object store, encryption or high availability. Other database backends are not supported or tested here. The renderer is controlled and the printer is a database fixture; no job is physically printed and no normal demo data is changed. The file check reads the Record Files rows and object bytes directly, not through a product service.
+
 ## Session cleanup status
 
 Ending a session (`MobileSessionService`) first persists the ended state with `authCleanupStatus = PENDING`. Cleanup then sets `REQUESTED` (with `authCleanupAt`) **before** calling the logout executor and removing the stored core session. If that call throws a `QException`, the status becomes `RETRY_NEEDED`. So `REQUESTED` means cleanup was attempted and no failure was reported; it is not independent proof that the provider session is gone. Cleanup is skipped when a binding does not exist, and for a single end inside an open transaction; a status left at `PENDING` also needs a retry. The bulk End Session process commits all tombstones first and runs cleanup afterwards.
@@ -29,11 +45,11 @@ To retry: find sessions with `authCleanupStatus` of `RETRY_NEEDED` or `PENDING`
 
 ## Retention
 
-Scans, sessions, bindings and Echo scans are **kept indefinitely** by default. Table deletes are blocked by permissions and foreign keys tie history to devices. Barcode payloads and last-known location are retained, so retention is a deliberate host decision: any purge is a host DBA procedure, taken with a snapshot first and respecting the foreign keys. Audit is current-state only; revoking overwrites the previous approver and time.
+Scans, sessions, bindings and Echo scans are **kept indefinitely** by default. Table deletes are blocked by permissions and foreign keys tie history to devices. Barcode payloads and last-known location are retained, so a different retention period is a host-owned policy, not a feature of this release: any purge is a host DBA procedure, taken with a snapshot first and respecting the foreign keys. Audit is current-state only; revoking overwrites the previous approver and time.
 
 ## Database migration beyond H2
 
-The supplied, tested scripts are H2: `src/main/resources/db/mobile-scanners-h2.sql` and the Echo `echo-h2.sql`. For any other backend the **host owns the equivalent migration**; do not assume `ADD COLUMN IF NOT EXISTS` or the column types. Additive columns that older databases need before running current servers: on `mobileScan`, nullable `aimIdentifier` (`VARCHAR(3)`) and `rawDataBase64`; on Echo, nullable `echo_scan.aimIdentifier`, `rendererValue` and `humanReadable`, and **`echo_run.copies`, which is `INT NOT NULL DEFAULT 1`** (existing runs keep one copy), so it is not nullable and the equivalent migration must supply the default. Echo also has nullable template columns (`templateId`, `templateRevisionId`) in `echo-h2.sql`. Test the migration on a copy, and snapshot first.
+The supplied, tested scripts are H2: `base/src/main/resources/db/mobile-scanners-h2.sql` and the Echo `echo-h2.sql`. Other backends are unsupported and untested here; a host that uses one **owns the equivalent migration**; do not assume `ADD COLUMN IF NOT EXISTS` or the column types. Additive columns that older databases need before running current servers: on `mobileScan`, nullable `aimIdentifier` (`VARCHAR(3)`) and `rawDataBase64`; on Echo, nullable `echo_scan.aimIdentifier`, `rendererValue` and `humanReadable`, and **`echo_run.copies`, which is `INT NOT NULL DEFAULT 1`** (existing runs keep one copy), so it is not nullable and the equivalent migration must supply the default. Echo also has nullable template columns (`templateId`, `templateRevisionId`) in `echo-h2.sql`. Test the migration on a copy, and snapshot first.
 
 ## Demo-only file adapters
 

docs/PRODUCTION-READINESS.md

@@ -6,27 +6,29 @@
 
 | Area | Evidence (see session state for revisions and counts) |
 | --- | --- |
-| Server source and development publication | `develop` at `a9eae04` (PR 17 merge; includes PR 13 and the committed GS1 and photo-capture source); PR 12 snapshot `0.1.0-20261103.233448-3645` read back anonymously and matches reviewed source. |
-| Android host libraries | `main` at `0ae2101`; SDK run 3634 passed and artifacts verified. Development libraries only. |
-| Current cohort tests | Final merged source: 193 server tests and Checkstyle pass; Android 232 unit tests and lint pass. Inherited report-only guardrail findings remain visible; qualified owner dependencies are still required. |
-| Local runtime | One server on public QQQ RC.21 and Printing 1.0.0; API 1.10, mobile 1.5, printing 2.3, mobile-record-files 1.0; existing data preserved. |
+| Server source and development publication | PR 19 merged as `9e8685f`, including record/photo UX support and earlier PR 17/18 changes; the storage/recovery patch is based on that source. Earlier PR 12 snapshot `0.1.0-20261103.233448-3645` was read back anonymously and matched its reviewed source. |
+| Android host libraries | Published development libraries from source `0ae2101`: SDK run 3634 passed and artifacts verified. The scanner application's newer source and signed candidate are recorded below. |
+| Current cohort tests | Combined five-module `verify` (2026-11-05): 196 server tests (53 / 8 / 22 / 74 / 39), zero failures, errors and skips, zero Checkstyle violations, with qualified private owner dependencies. Android 232 unit tests and lint pass. Inherited report-only guardrail findings remain visible. |
+| Storage integrity and recovery | `PrivateObjectFilesTest` concurrent-writer and dot-bucket regressions; `EchoDemoAcceptanceTest.restoredSnapshotKeepsScanAndRetainedFileAndRevertedApprovalStateIsReaudited` is the isolated local-demo recovery acceptance (stopped H2 plus object snapshot/restore, `RecordFilesTables.FILE` relationship and byte hashes). See [operations](OPERATIONS.md). |
+| Local runtime | One server using the tested development aggregate: public QQQ SNAPSHOT, current Collaboration, scoped local Record Files and qualified document inputs, plus Printing 1.0.0. API 1.10, mobile 1.5, printing 2.3, mobile-record-files 1.0; existing data preserved. Final immutable public-cohort qualification remains open. |
 | Device and admin processes | Enrollment, approval and revocation work from a single record and from bulk selection (checked rows, select-all, first N), with confirmation and visible results, covered by HTTP and browser E2E tests. Earlier browser run: 15 cases. |
-| Hardware | TC22 manual tests: operator-reported pass on November 4 (no per-case artifacts). MC9400 configured and approved; trigger check pending. |
+| Approved-scanner photos | Host-only `quarantineCapturedFiles=false` makes an approved device's captured JPEG/PNG `AVAILABLE`; other intake stays `QUARANTINED`. `record-files.release` is admin-only. Root-reported: 69 owner and 197 scanner/Echo tests passed, 13 focused Android tests passed, Checkstyle passed. A synthetic gallery PNG from the signed MC9400 app was `AVAILABLE` with exact parent/type/size/SHA-256. No camera-hardware or new full-preview proof. Depends on the unmerged Record Files owner PR 1. |
+| Hardware | TC22 manual tests: operator-reported pass on November 4 (no per-case artifacts). MC9400 physical trigger done: Saved scan with backend EMDK CODE128/AIM/raw bytes and attribution confirmed (the barcode was not the requested literal). |
 
 ## Open gates
 
-The maintained server and existing TC22 app now run the GS1, rich test-data and record UX changes. Actions → Add photo, grouped/related records, search/filter/Back state and the saved-photo gallery are implemented and verified by isolated native acceptance plus an actual TC22 visual pass. Existing data and enrollment were preserved. See [current evidence](history/MOBILE-UX-2026-11-05.md). This supersedes the earlier undeployed status; physical GS1 print/rescan and signed-build production deployment remain open. The user authorized normal source commit/push/merge, not a new artifact release.
+The maintained server and existing TC22 app now run the GS1, rich test-data and record UX changes. Actions → Add photo, grouped/related records, search/filter/Back state and the saved-photo gallery are implemented and verified by isolated native acceptance plus an actual TC22 visual pass. Existing data and enrollment were preserved. See [current evidence](history/MOBILE-UX-2026-11-05.md). This supersedes the earlier undeployed status; physical GS1 print/rescan and signed-build production deployment remain open. The user authorized the final release, signing and publication for this bounded goal; Android PR 15 (`c782aaaaba3f62422232436a9000af9d4b38fc82`) merged after all CI.
 
 | Gate | What is still required |
 | --- | --- |
-| Public dependency cohort | Public, coherent Generation/bridges/Record Files/Scripting artifacts from their owner; adoption of the Core/Collaboration/Next UI foundations when released. Today these are qualified owner inputs. |
-| Release | Final combined CI on the final revisions (a fresh full gate and browser E2E re-run), a reviewed release manifest, and release/RC publication, which stays disabled until then. Redesign of the shared CI pipeline is outside this scope. |
-| Signing and distribution | Done: QRun key with backup, signed 1.0 APK, direct/MDM channel. Open: qualification of the signed build on a device against an HTTPS server, then distribution and update path. A signed preview is published; it is not a qualified production rollout. No signing CI. Deferred by the user to the very end. |
-| Deployment | HTTPS and the host's identity provider, supported database migration beyond the supplied H2 schema, and an executed restore drill. Single-instance procedure, recovery and retention guidance is written in [operations](OPERATIONS.md); it is a procedure, not an executed drill, and claims no production storage. The HTTP loopback demo is not a production deployment. |
-| Provider authentication | Native OAuth2 requires UI API 1.10 native-session and nonce-validation support on the server (verified in the Android source). Still open: acceptance against a configured provider (such as Authentik) on a native handheld, including logout and account switching. No such handheld test is claimed. |
-| Further device qualification | MC9400 physical trigger check and MDM-applied managed configuration remain unverified. The TC22 camera, GPS and screen-viewing checks are covered by the accepted operator group report; no separate per-case evidence is claimed or required again for that demo. |
+| Public dependency cohort | Public, coherent Generation/bridges/Record Files/Scripting artifacts from their owner; adoption of the Core/Collaboration/Next UI foundations when released. Today these are qualified owner inputs, and the current local aggregate uses public Core SNAPSHOT, current Collaboration and a local Record Files change, not a final public cohort. |
+| Release | Retest the full gate when the final public dependency cohort is adopted, with a reviewed release manifest; Maven publication stays disabled until then. Redesign of the shared CI pipeline is outside this scope. |
+| Signing and distribution | Done: QRun key with backup, signed Android 1.0.1 (code 3) built from the merged PR 15 source tree and installed in place on an MC9400 (installed bytes match; login/enrollment preserved; Scan Capture reopened; HTTPS connected). Open: public dependencies, signing-APK download publication and final distribution. No signing CI. |
+| Deployment | HTTPS and the host's identity provider. Single-instance procedure, recovery and default-indefinite, host-owned retention guidance is in [operations](OPERATIONS.md); isolated local-demo recovery acceptance has passed. Enterprise object-store/HA and non-H2 databases are unsupported and unqualified options, not release tasks. The HTTP loopback demo is not a production deployment. |
+| Provider authentication | Native OAuth2 requires UI API 1.10 native-session and nonce-validation support on the server (verified in the Android source). Shared Authenticator server configuration is verified (trusted HTTPS, API 1.10, scanner and printing extensions and channels, exact callbacks, REQUIRED nonce). Still open: native Authentik login, logout and account switching on a handheld (needs the MC9400 wireless-debugging endpoint). No native-auth pass is claimed. The Printing client nonce fix (PR 11, `443f642`; 352 tests and build passed) awaits hosted Core. |
+| Further device qualification | MDM-applied managed configuration remain unverified. Company profile/wallpaper is separate tracked scope, not a blocker for this release goal. The TC22 camera, GPS and screen-viewing checks are covered by the accepted operator group report; no separate per-case evidence is claimed or required again for that demo. |
 | Barcode fidelity | Echo's supported profiles are documented ([limits](../examples/echo/README.md#fidelity-and-limits)); The committed source supports bounded GS1-128; physical print/rescan remains open. Other GS1, ECI, structured and binary profiles remain refused. No universal barcode-reproduction claim. |
-| Final reviews | Reconcile the dated security, architecture and standards reports to the final revision; they are scoped historical reviews, not a fresh exhaustive scan. A dated static review of base `a9eae04` with its scope and limits is in [review reconciliation](REVIEW-RECONCILIATION-2026-11-05.md); it is not an audit rating. |
+| Final reviews | Reconcile the dated security, architecture and standards reports to the final revision; they are scoped historical reviews, not a fresh exhaustive scan. A dated static review of base `a9eae04`, its supplement and its scope and limits are in [review reconciliation](REVIEW-RECONCILIATION-2026-11-05.md); it is not an audit rating. |
 
 ## Rules that stay in force
 

docs/REVIEW-RECONCILIATION-2026-11-05.md

@@ -21,6 +21,17 @@ This records what one static review covered. It is not an audit rating and not a
 - `UI-API.md` operation table now lists all seven operations; root `pom.xml` url, scm and issue tracker point at Gitea.
 - Deferred: the screen-upload 409 and every other operation's 409 share the generic text "Installation already enrolled" in `MobileJsonSpec`. Correcting it is a contract text change needing a patch version bump and regenerated YAML, so it is not done here.
 
+## Supplement: findings checked after the review
+
+Scope: the four findings raised after the static review. This is not an audit rating or a score.
+
+- **F1, concurrent metadata overwrite:** fixed in `PrivateObjectFiles` and regression-tested by `PrivateObjectFilesTest.lateSecondWriterIsRefusedAndFirstWritersBytesAndMetadataRemain` (also `existingObjectIsNeverReplaced`). The controlled interleaving reproduced mismatched metadata on the old implementation; all eight storage tests then passed with the fix.
+- **F2, dot bucket traversal:** fixed and regression-tested by `PrivateObjectFilesTest.dotBucketsAreRefusedAndValidBucketsStillWork` (also `keysCannotTraverseOrAlias`).
+- **F3, ZPL command injection:** disproven at source. In the owner Generation renderer, `ZplRenderer.java` lines 326-331 encode every UTF-8 byte under `^FH`. `RendererTest.typedZplEscapesCommandsAndEmitsRasterBarcodes` covers `^XA`, `~JA` and underscore input. That source is owner-held; the exact published artifacts are still pending qualification.
+- **F4, label clipping:** the assumption is guarded by renderer placement bounds, which refuse overwide text. No universal media-fidelity claim is made.
+
+The fixes were verified by the 2026-11-05 combined five-module `verify` (196 tests, zero failures, errors and skips, zero Checkstyle violations) on qualified private owner dependencies, not on published artifacts. Pending: owner artifact qualification, physical output and any enterprise object-store or high-availability recovery (unsupported, not tasks of this release).
+
 ## Inherited guardrail heuristics (visible, not disabled)
 
 Two generic guardrail reports are heuristic mismatches, not missing behavior. They stay visible as existing signals; no check was disabled and no test marker was added to satisfy them.

docs/SESSION-STATE.md

@@ -6,7 +6,7 @@ Current as of **2026-11-05**. Open work is in [TODO](TODO.md), release gates in
 
 GS1-128 duplication, including barcode and printed HRI, is merged through [PR 15](https://git.kof22.com/QRun-IO/qbit-mobile-scanners/pulls/15), commit `f9b0eb2`, and included in the [Forge source prerelease](https://git.kof22.com/QRun-IO/qbit-mobile-scanners/releases/tag/echo-gs1-source-20261104). This is source publication, not a published Echo Maven dependency. PRs 17 and 18 add publication metadata, the frozen contract baseline and recovery guidance; those changes are retained in this feature branch.
 
-The [rich demo fixture](MOBILE-TEST-DATA.md) and [record UX improvements](history/MOBILE-UX-2026-11-05.md) are implemented. Native browsing, record Actions and photo presentation belong to the companion Android repository. The user authorized committing, pushing and merging both repositories; source review follows ordinary Gitea checks. No new artifact release is included.
+The [rich demo fixture](MOBILE-TEST-DATA.md) and [record UX improvements](history/MOBILE-UX-2026-11-05.md) are implemented. Native browsing, record Actions and photo presentation belong to the companion Android repository. The user authorized the final release, signing and publication for this bounded goal. Android [PR 15](https://git.kof22.com/QRun-IO/qqq-android/pulls/15) merged as `c782aaaaba3f62422232436a9000af9d4b38fc82` after all CI. Maven publication switches stay disabled until the public dependency cohort is adopted.
 
 | Item | State |
 | --- | --- |
@@ -22,20 +22,30 @@ The maintained composed Echo server and **existing TC22 app** were updated in pl
 
 Use **Test Data → Test Orders → a record → Actions → Add photo**. Details, Items, History and Photos tabs provide direct access. Search/filter/count and Back preserve table context. Approved photos have thumbnails/previews; quarantined uploads remain listed as awaiting review. Ordinary read/attach permissions still apply.
 
-The [local demo](LOCAL-DEMO.md) uses public QQQ `4.1.0-RC.21`, released Printing `1.0.0`, and qualified document/files/scripting owner inputs. Host port is `57832`; device port 8080 forwards to it, retaining the app URL `http://127.0.0.1:8080`. Contract versions remain UI API 1.10, mobile-scanners 1.5, printing 2.3 and mobile-record-files 1.0. This loopback demo is separate from HTTPS production deployment.
+**Approved-scanner photos.** The Echo host sets Record Files `quarantineCapturedFiles=false`, so a JPEG/PNG captured by a currently approved device is `AVAILABLE` at once. Uploads, imports and attachment-panel files stay `QUARANTINED`. Parent tables are Echo scans plus the test orders, items and events; the scanner's existing `.attach` grants are retained. Only `admin` gains `record-files.release`; scanner grants are unchanged. Three earlier quarantined photos were released through the audited admin Release process. The server's current aggregate was built from public Core SNAPSHOT, current Collaboration, the scoped local Record Files change and qualified private document inputs, not a final public cohort. The scoped Record Files change is [owner PR 1](https://git.kof22.com/QRun-IO/qbit-record-files/pulls/1) (policy commit `3f08c584`), open and unmerged; its public CI currently fails an enrollment check that the coordinator owns, so neither the check nor its merge gates are changed here. No version or POM was guessed.
+
+The [local demo](LOCAL-DEMO.md) source defaults remain QQQ `4.1.0-RC.21` and Printing `1.0.0` pending the public-cohort update; the maintained runtime uses the verified development aggregate described above. Host port is `57832`. The TC22 development app retains its loopback forwarding; the signed MC9400 app connects through trusted HTTPS. Contract versions remain UI API 1.10, mobile-scanners 1.5, printing 2.3 and mobile-record-files 1.0. This is local development qualification, not a customer production deployment.
 
 ## Verification
 
-- The final merged-source cohort passed **193 server tests**: scanner 53, base demo 8, mobile Record Files 22, Echo 74, Echo demo 36, with Checkstyle. The new build parent contributes four guardrail tests; its report-only schema-location/contract-test findings remain visible. Source/resource copies were hash-checked; private owner coordinates were overridden only in the isolated verification build.
+- Photo/admin change set (root-reported, not rerun in this review): 69 owner tests and 197 scanner/Echo tests passed (runs of 31, 158 and 8), 13 focused Android tests passed, and the relevant Checkstyle passed. These groupings differ from the module split below, so no per-module counts are claimed. Public immutable dependency qualification is still pending.
+- Live evidence: a fresh synthetic gallery PNG uploaded from the production-signed MC9400 app returned "Saved photo", and the server showed `AVAILABLE` with the exact parent, type, size and SHA-256. An older photo's Available state, thumbnail and Preview control were observed. The new photo's full preview was not clicked because ADB disconnected. No camera-hardware or full-preview proof is claimed.
+- The earlier combined five-module `verify` (2026-11-05, base `9e8685f` plus the storage fixes) passed **196 server tests** with zero failures, errors and skips and zero Checkstyle violations: scanner 53, base demo 8, mobile Record Files 22, Echo 74, Echo demo 39. It used qualified private owner dependencies; there is no public-dependency or physical-output qualification, and the gate must be repeated when the public cohort is adopted. The new build parent's report-only schema-location/contract-test findings remain visible.
+- Storage/recovery PR 21 is merged (`59959247`), with bounded cold-restore and race proof complete. Website 0.1.17 is complete. Evidence: `PrivateObjectFilesTest.concurrentSameKeyWritersLeaveOneWinnersBytesAndMetadata` and `dotBucketsAreRefusedAndValidBucketsStillWork`; recovery acceptance `EchoDemoAcceptanceTest.restoredSnapshotKeepsScanAndRetainedFileAndRevertedApprovalStateIsReaudited` (details in [OPERATIONS](OPERATIONS.md#isolated-local-demo-recovery-acceptance-automated-passed)).
 - Android passed **232 unit tests**, lint with **0 errors/0 warnings**, and the debug APK build. E2E APK/instrumentation builds and eight runner guard tests also passed.
 - Isolated MC9400 native acceptance passed search/filter/paging/Back, grouped/related records, camera/gallery upload, parent-scoped saved-photo list, approved preview, rotation, pending-upload navigation protection and forced-logout cleanup. All requests matched the semantic API. Process-photo regression also passed.
 - The final date-only correction received unit/lint/build checks and actual TC22 verification. Actual-device screenshots confirm Actions → Add photo, dates/timezones, currency, related tabs, photo empty state and return to page two. Synthetic camera/gallery inputs in automated acceptance are not a new operator camera report.
 - Earlier 135/188/198/377-test cohorts and 15 browser E2E cases are historical evidence, not a fresh run against future public dependencies. The snapshot source comparison applies to its original revision only.
+- 2026-11-06, branch `fix/refresh-device-versions`: the MC9400 in-place 1.0.0 to 1.0.1 update left the device record and every later scan reporting `appVersion` 1.0.0, because only enrollment ever wrote `manufacturer`/`model`/`osVersion`/`appVersion` and no later client request carried them. Extension 1.6 adds the same optional fields to `MobileScannersHeartbeatRequestV1`; the heartbeat refreshes the device record when a value differs and scans copy the refreshed record (see [UI-API](UI-API.md)). The Android host change (send `osVersion`/`appVersion` on heartbeat) is on the same-named branch in the Android repository; devices need that client build before their versions refresh. Root module: 56 tests, zero Checkstyle violations, new baseline `mobile-scanners-1.6.0.yaml`.
 
 ## Handhelds and remaining limits
 
-Current TC22 APK SHA-256: `F71033C835AC3EB361A04D78C842947C5A04C85CE1AB1B999AA8CEFBFC9D7A95`. Matching signer and installed bytes were verified; the same app reopened connected and signed in. Prior preview hashes are in [history](history/RICH-RECORDS-2026-11-05.md).
+Previous TC22 APK SHA-256: `F71033C835AC3EB361A04D78C842947C5A04C85CE1AB1B999AA8CEFBFC9D7A95`; prior preview hashes are in [history](history/RICH-RECORDS-2026-11-05.md).
 
-The November 4 TC22 operator group pass remains accepted and is not requested again. MC9400 remains configured and approved; its physical trigger/backend check is outstanding. Physical GS1 print/rescan, signed-build HTTPS qualification, provider callback acceptance and fleet rollout remain open. Echo supports only its documented [barcode profiles](../examples/echo/README.md#fidelity-and-limits).
+Signed Android `1.0.1` (code 3) was built from the identical merged source tree (PR 15) and installed in place on the MC9400. The installed bytes match the built APK, login and enrollment were preserved, the authorized Scan Capture screen reopened, and the HTTPS connection was established. The MC9400 physical trigger is **done**: an actual operator trigger produced a Saved scan, and the backend confirmed EMDK CODE128, AIM and raw bytes with server-derived attribution. The barcode scanned was not the literal string requested, so no exact-test-string claim is made.
 
-Operations and restoration guidance is in [OPERATIONS](OPERATIONS.md); no restore drill is claimed. The [dated review](REVIEW-RECONCILIATION-2026-11-05.md) remains scoped to its recorded base. Public owner dependencies require a separate reviewed adoption and new gate.
+Shared Authenticator server configuration is verified: real trusted HTTPS, UI API 1.10, both scanner and printing extensions and channels, exact callbacks and a REQUIRED nonce. Native client login, logout and account switching are **not yet tested** (this needs the MC9400 wireless-debugging endpoint), so no native-auth pass is claimed. The Printing client required-nonce fix (PR 11, `443f642`; 352 Windows/CLI tests and build passed) awaits hosted Core. Pending: native Authentik login/logout/account switching, the final public Core/Collaboration/document/files/scripting/bridge artifacts, a public-cohort rerun, GS1 physical print/rescan, signing-APK download publication and owned cleanup.
+
+The November 4 TC22 operator group pass remains accepted and is not requested again. Physical GS1 print/rescan, provider callback acceptance and fleet rollout remain open. Echo supports only its documented [barcode profiles](../examples/echo/README.md#fidelity-and-limits). Company profile/wallpaper is separate tracked scope, not a blocker for this release goal.
+
+Operations and recovery guidance is in [OPERATIONS](OPERATIONS.md). The automated stopped-H2 plus object snapshot/restore case passed as isolated local-demo recovery acceptance (no physical printing, no normal demo data changed). Enterprise object-store/HA and non-H2 databases are unsupported and unqualified, not release tasks. The [dated review](REVIEW-RECONCILIATION-2026-11-05.md) records its scope and supplement. Public owner dependencies require a separate reviewed adoption and a new gate.

docs/TODO.md

@@ -9,10 +9,12 @@ Open work only, as of **2026-11-05**. Present status is in [session state](SESSI
 
 Note: redesign of the shared CI pipeline is outside this scanner/local Echo scope and is not tracked here; the local demo does not depend on it.
 
+- [ ] **Record Files `quarantineCapturedFiles`.** The Echo host (`EchoDemo`) and the optional integration test already call/require `RecordFilesQBitConfig.withQuarantineCapturedFiles(Boolean)` (nullable, null inherits `quarantineNewFiles`; applies only to CAPTURE intake with a provider-verified device identity). The owner's scoped change (policy commit `3f08c584`, PR 1) is open and unmerged, and its CI currently fails a not-enrolled check owned by the coordinator; do not change CI or weaken merge gates. Adopt the released version as a reviewed pin once public; no coordinate is known, so none was guessed and this source builds only against the local owner input until then.
+
 ## This repository
 
 - [ ] Qualify GS1 template/media setup and **physical print/rescan** of the requested label profile. Software duplication, native acceptance and maintained-demo adoption are complete.
-- [ ] Exercise the [operations](OPERATIONS.md) backup/restore procedure on the selected deployment (not yet executed), and decide retention.
+Retention stays indefinite by default and any change is a host-owned policy ([operations](OPERATIONS.md#retention)). Enterprise object-store and high-availability recovery, and database backends other than H2, are unsupported/unqualified deployment options, not tasks of this release. The 2026-11-05 gate (196 tests, zero failures/errors/skips, zero Checkstyle violations) used qualified private owner dependencies; the required public-cohort rerun remains listed below.
 - [ ] Optionally correct the generic 409 text in `MobileJsonSpec` (screen upload is a stale-frame conflict) with a patch version bump and regenerated contract; deferred.
 - [ ] Complete the authorized readiness work in [the active plan](GS1-RECORD-PHOTOS-PLAN.md), retaining explicit external/hardware gates.
 
@@ -21,13 +23,15 @@ Note: redesign of the shared CI pipeline is outside this scanner/local Echo scop
 
 ## Hardware and device follow-up
 
-- [ ] **MC9400:** one physical trigger scan, then confirm the backend record. The device is installed, signed in and approved ([session state](SESSION-STATE.md#handhelds)).
+- [ ] Native Authentik login, logout and account switching on a handheld (not yet tested; needs the MC9400 wireless-debugging endpoint). The shared Authenticator server configuration is verified; the Printing client nonce fix (PR 11) awaits hosted Core. The MC9400 physical trigger check is done ([session state](SESSION-STATE.md#handhelds-and-remaining-limits)).
+- [ ] Optional: click the full preview of the newly uploaded gallery photo on a handheld (not observed because ADB disconnected). No camera-hardware proof is claimed.
 - [ ] Optional: capture per-case evidence (photos, logs, a scanned-back label) on a future run. The November 4 operator pass is accepted as is and is not to be requested again.
 
 ## Release (deliberately last)
 
-- [ ] Signed-build qualification on a device against an HTTPS server (enrollment, scanner path, navigation, update), then distribution. The QRun key, signed 1.0 APK and direct/MDM channel are done; a signed preview is published, but no production rollout or automatic APK-signing CI is qualified.
-- [ ] HTTPS deployment, host-owned database migration beyond H2, and the remaining gates in [production readiness](PRODUCTION-READINESS.md).
+- [ ] Final distribution of the signed 1.0.1 build and the public dependencies it waits on. Signing is done: the build was installed in place on an MC9400 through ADB, preserved enrollment, and reopened Scan Capture against the HTTPS server. Remaining device checks are listed above; no automatic APK-signing CI is qualified. Also open: signing-APK download publication, owned cleanup, and a rerun of the public cohort with the final public Core/Collaboration/document/files/scripting/bridge artifacts.
+- [ ] Company profile/wallpaper is a separate tracked scope and not a blocker for this bounded release goal.
+- [ ] HTTPS deployment by the host (any non-H2 migration is host-owned and unsupported here) and the remaining gates in [production readiness](PRODUCTION-READINESS.md).
 
 ## Not in version one
 

docs/UI-API.md

@@ -1,6 +1,6 @@
 # Mobile Scanners semantic UI API
 
-Mobile Scanners is an independently versioned QQQ UI API extension. `MobileScannersQBitProducer` registers the `mobile-scanners` contract, currently **1.5.0** (core UI API 1.10 on the maintained local server), through `MiddlewareSpecExtensionsMetaData`. The framework generates its routes, discovery advertisement and merged OpenAPI from the same endpoint specs. Optional operator-consented device-screen viewing is described in [DEVICE-SCREEN-VIEWING.md](DEVICE-SCREEN-VIEWING.md); app-content remains the default. There is no separate `/mobile/v1` API or legacy alias.
+Mobile Scanners is an independently versioned QQQ UI API extension. `MobileScannersQBitProducer` registers the `mobile-scanners` contract, currently **1.6.0** (core UI API 1.10 on the maintained local server), through `MiddlewareSpecExtensionsMetaData`. The framework generates its routes, discovery advertisement and merged OpenAPI from the same endpoint specs. Optional operator-consented device-screen viewing is described in [DEVICE-SCREEN-VIEWING.md](DEVICE-SCREEN-VIEWING.md); app-content remains the default. There is no separate `/mobile/v1` API or legacy alias.
 
 The host must also install `MobileScannersRouteProvider` on the same server. This provider binds verified device headers to the current request; it does not register additional business routes. Keep the versioned QQQ routes enabled. The qbit registers the `android` client channel while preserving the host's existing channel policies. The demo disables legacy unversioned middleware routes.
 
@@ -36,6 +36,8 @@ Public discovery, OpenAPI, branding and connectivity ignore stale device headers
 
 Enrollment takes `MobileScannersEnrollRequestV1`: required canonical UUID `installationId`, optional `displayName`, `manufacturer`, `model`, `osVersion` and `appVersion` strings, each at most 200 characters. The JSON request body is limited to 4096 characters. A duplicate installation returns HTTP 409 and never rotates or discloses its existing credential. A new installation starts `PENDING` and receives its private `deviceToken` once.
 
+Since extension 1.6, `MobileScannersHeartbeatRequestV1` also accepts the same optional `manufacturer`, `model`, `osVersion` and `appVersion` strings (at most 200 characters, 400 otherwise). An approved device's record is updated only when a sent value differs; omitted, null or blank values leave the enrolled values unchanged. Scan events copy the device record at save time, so an in-place app or OS update is reflected on the next heartbeat and every later scan, while earlier scans keep the versions that produced them. The Android host sends `osVersion` and `appVersion` on every heartbeat.
+
 Send `X-QQQ-Device-Id` and `X-QQQ-Device-Token` on authenticated device/core metadata, widget and process requests to this same origin. The device ID is a UUID; the token is private and at most 128 characters. These headers supplement the authenticated user session. They never replace user permission checks. Never put a token in metadata, URLs, process values, screenshots, logs or fixtures; never forward credentials to a branding asset origin. Store the issued credential privately. Only its digest is stored server-side.
 
 `devices/current` returns `deviceId`, `displayName` and `status`, never a token. `PENDING` and `REVOKED` devices may read their status. Scanner access still requires `APPROVED`, checked when launching and saving, including asynchronous/resumed execution. Device approval/revocation uses the ordinary QQQ processes, including single-record and bulk selections.
@@ -81,7 +83,7 @@ Schema migration (H2, idempotent, nullable): `ALTER TABLE mobileScan ADD COLUMN
 
 ## Contract checks and compatibility
 
-The published fragment is [mobile-scanners.yaml](../src/main/resources/openapi/qqq-v1/mobile-scanners.yaml); the initial release baseline is [mobile-scanners-1.0.0.yaml](../src/test/resources/openapi/mobile-scanners-1.0.0.yaml), with additional frozen baselines such as [mobile-scanners-1.4.0.yaml](../src/test/resources/openapi/mobile-scanners-1.4.0.yaml) (the contract immediately before the 1.5.0 capture metadata) and [mobile-scanners-1.5.0.yaml](../src/test/resources/openapi/mobile-scanners-1.5.0.yaml), the frozen 1.5.0 release snapshot that later changes are checked against. `MobileScannersApiContractTest` rejects generated-document drift, unresolved contract structure, incompatible baseline changes and missing version bumps using QQQ's shared contract checker. Object required fields and scanner numeric bounds are standard OpenAPI keywords, added by small Schema subclasses because RC20's base model does not expose those setters.
+The published fragment is [mobile-scanners.yaml](../base/src/main/resources/openapi/qqq-v1/mobile-scanners.yaml); the initial release baseline is [mobile-scanners-1.0.0.yaml](../base/src/test/resources/openapi/mobile-scanners-1.0.0.yaml), with additional frozen baselines such as [mobile-scanners-1.4.0.yaml](../base/src/test/resources/openapi/mobile-scanners-1.4.0.yaml) (the contract immediately before the 1.5.0 capture metadata) and [mobile-scanners-1.5.0.yaml](../base/src/test/resources/openapi/mobile-scanners-1.5.0.yaml), the frozen 1.5.0 release snapshot that later changes are checked against. `MobileScannersApiContractTest` rejects generated-document drift, unresolved contract structure, incompatible baseline changes and missing version bumps using QQQ's shared contract checker. Object required fields and scanner numeric bounds are standard OpenAPI keywords, added by small Schema subclasses because RC20's base model does not expose those setters.
 
 For an intentional contract edit, update specs/schemas and the extension semantic version, then regenerate only the current fragment:
 

examples/echo/demo/CLAUDE-HANDOFF.md

@@ -16,7 +16,7 @@ Date: 2026-11-02. Scope: `examples/echo/demo/**`. Source checkpoint, not a relea
 
 `EchoDemo` extends `MobileScannersDemo` (database, `scanner`/`admin` accounts, native server) and composes Collaboration, Record Files, Printing, Document Generation and `EchoHost.install` from their public classes on one private H2 file (`WRITE_DELAY=0`). Composition runs under a scoped system context that is restored afterwards, then `QInstanceEnricher` enriches the instance, because the server only validates and the enricher registers Collaboration's record-feature permissions. `LocalFilesystemAttachmentStorage` implements the attachment owner's storage SPI over `PrivateObjectFiles` (hashed keys, temp-file-then-link, no overwrite) and adds no policy. `TrustedLocalEchoDemo` is the explicit developer launcher; the production `EchoDemo` default fails closed. See `README.md` for build, run and environment.
 
-Authentication is the existing demo password/session module plus exact grants. `scanner`: `echo.use`, `printing_operator`, `document-generation.view|generate|print`, `record-files.view|manage`, `echoScan.attach` and the `printing_tenant` row key (replaced, never appended, on each validation); then `CollaborationSecurity.applyToSession`. `admin` additionally: `printing_admin`, `document-generation.configure|publish`. No Record Files release/configure/audit for anyone.
+Authentication is the existing demo password/session module plus exact grants. `scanner`: `echo.use`, `printing_operator`, `document-generation.view|generate|print`, `record-files.view|manage`, `echoScan.attach` and the `printing_tenant` row key (replaced, never appended, on each validation); then `CollaborationSecurity.applyToSession`. `admin` additionally: `printing_admin`, `document-generation.configure|publish`, `record-files.release` (so approved captured photos release through the normal audited process). The scanner never gets release; no Record Files configure/review/audit for anyone.
 
 ## Test isolation
 

examples/echo/demo/README.md

@@ -15,7 +15,7 @@ There is **no default port**: pass one as the argument or set `ECHO_DEMO_PORT`.
 
 ## Status
 
-The demo and Echo library tests pass with Checkstyle clean (current cohort: Echo 68, composed demo 35 tests; see [session state](../../../docs/SESSION-STATE.md)). The QQQ default is 4.1.0-RC.21 and Printing defaults to released 1.0.0; the other owner qbits remain qualified owner inputs until their public release. The composed acceptance test passes with a controlled synthetic renderer and a simulated Printing queue, so it is **not physical output**. TC22 physical acceptance is separately operator-reported as passing (November 4, group report). Not production-ready and not a public SDK release. The dated [`CLAUDE-HANDOFF.md`](CLAUDE-HANDOFF.md) is a historical checkpoint.
+The demo and Echo library tests pass with Checkstyle clean (counts change per run; see [session state](../../../docs/SESSION-STATE.md) for the latest reported results). The QQQ default is 4.1.0-RC.21 and Printing defaults to released 1.0.0; the other owner qbits remain qualified owner inputs until their public release. The composed acceptance test passes with a controlled synthetic renderer and a simulated Printing queue, so it is **not physical output**. TC22 physical acceptance is separately operator-reported as passing (November 4, group report). Not production-ready and not a public SDK release. The dated [`CLAUDE-HANDOFF.md`](CLAUDE-HANDOFF.md) is a historical checkpoint.
 
 ## Trusted local development launcher
 
@@ -88,7 +88,7 @@ The legacy `ECHO_TEMPLATE_ID`, `ECHO_TEMPLATE_MEDIA_ID` and `ECHO_TEMPLATE_MEDIA
 
 ## Accounts and permissions
 
-`scanner` receives exactly: `echo.use`, `printing_operator`, `document-generation.view|generate|print`, `record-files.view|manage` (manage is the owner's intake permission) and the `printing_tenant` row key. `admin` receives the same plus `printing_admin` (Printing's native pairing/approval/setup processes) and `document-generation.configure|publish` to prepare templates. The scanner never gets these, and nobody gets Record Files release/configure/audit. Scans still need an enrolled and approved device, so use the existing mobile enrollment flow.
+`scanner` receives exactly: `echo.use`, `printing_operator`, `document-generation.view|generate|print`, `record-files.view|manage` (manage is the owner's intake permission), `.attach` on `echoScan` and the three mobile test-data tables (`testOrder`, `testOrderItem`, `testOrderEvent`) and the `printing_tenant` row key. `admin` receives the same plus `printing_admin` (Printing's native pairing/approval/setup processes) and `document-generation.configure|publish` to prepare templates. The scanner never gets these. Only `admin` also receives `record-files.release`, so approved captured photos can be released through the normal audited process; nobody gets Record Files configure/review/audit. Scans still need an enrolled and approved device, so use the existing mobile enrollment flow.
 
 ## Operator order
 
@@ -101,10 +101,11 @@ The legacy `ECHO_TEMPLATE_ID`, `ECHO_TEMPLATE_MEDIA_ID` and `ECHO_TEMPLATE_MEDIA
 The host also installs the existing `qbit-mobile-scanners-record-files` integration, so an approved scanner can attach photos to one of its own retained Echo scans. Nothing new is served: Record Files' registered, versioned `record-files` upload API (`/qqq/v1/qbit/record-files/...`) and the independently versioned `mobile-record-files` widget vocabulary are advertised in `/qqq/v1/version`, behind the same native auth and device guards.
 
 - **Process:** `echoScanPhotos` ("Echo scan photos"), listed in the Echo app. It requires `echo.use`, `echoScan.attach` and a verified approved device. The first step lists the actor's own scans (the table's record security lock decides; label is the barcode and type, never the record id). The server then re-reads the chosen scan through the collaboration owner's visibility and `attach` checks and builds the `RECORD_FILES_CAPTURE` widget from the record that check returned, on the fixed `echoScan` table. The client never supplies a table or record reference, and rendering the widget directly names no parent. Record Files authorizes the parent again on every upload operation.
-- **Policy:** JPEG/PNG only, 20 MiB per file, up to four files, 256 KiB chunks, private staging under the demo's `objects` directory (separate staging namespace). Retained originals follow the existing Record Files quarantine setting.
-- **Needs a real scan first:** the list is empty until the scanner has Echo scans. Nothing is seeded outside this module's tests.
+- **Policy:** JPEG/PNG only, 20 MiB per file, up to four files, 256 KiB chunks, private staging under the demo's `objects` directory (separate staging namespace). The Echo host sets Record Files' `quarantineCapturedFiles=false` (leaving `quarantineNewFiles=true` and the generated-file setting unchanged), so a JPEG/PNG saved from this process by a device that `MobileCaptureIdentityProvider` currently verifies as approved is registered `AVAILABLE` and can be previewed immediately. The same upload API on any other host, and every upload, import or attachment-panel file here, stay `QUARANTINED` until released. This is a host trust decision, not a content scan or human review; no release event is written and review status is unchanged. **Requires a Record Files version that contains `RecordFilesQBitConfig.withQuarantineCapturedFiles(Boolean)`. The owner's change is an open, unmerged PR; this checkout's dependency pin has not been updated and builds only against the local owner input until a public version is pinned.** Files already uploaded stay `QUARANTINED` until released through the normal `record_files_file_record_files_release` process.
+- **Test-data records:** the host also registers the test orders, items and events as Record Files parents, so a scanner can add photos from a record's Actions menu. The same approved-device policy and authorization re-check apply. Release of any quarantined file is admin-only (`record-files.release`).
+- **Needs a real scan first (for the `echoScanPhotos` process):** the list is empty until the scanner has Echo scans. Nothing is seeded outside this module's tests.
 - **Existing databases:** the Record Files upload tables are added by the same tolerated-reapply schema step; plan the migration for a database from another version.
-- **Not claimed:** no real photo upload, native capture or device run has been verified here. That needs the Android host against this server.
+- **Not claimed:** one synthetic gallery PNG uploaded from the signed MC9400 app was observed `AVAILABLE` with matching parent, type, size and SHA-256 (see [session state](../../../docs/SESSION-STATE.md)). No camera-hardware capture and no full preview of that photo are claimed.
 
 ## Existing databases
 

examples/echo/demo/pom.xml

@@ -16,15 +16,15 @@
    <properties>
       <maven.compiler.release>21</maven.compiler.release>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-      <qqq.version>4.1.0-RC.21</qqq.version>
+      <qqq.version>4.1.0-RC.26</qqq.version>
       <mobile.version>0.1.0-SNAPSHOT</mobile.version>
       <echo.version>0.1.0-SNAPSHOT</echo.version>
-      <generation.version>0.1.0-SNAPSHOT</generation.version>
+      <generation.version>1.1.0-RC.1</generation.version>
       <renderer.version>${generation.version}</renderer.version>
-      <printing.version>1.0.0</printing.version>
-      <recordfiles.version>0.1.0-SNAPSHOT</recordfiles.version>
+      <printing.version>1.2.0-RC.1</printing.version>
+      <recordfiles.version>0.4.0-RC.1</recordfiles.version>
       <mobilerecordfiles.version>0.1.0-SNAPSHOT</mobilerecordfiles.version>
-      <collaboration.version>0.1.0-record-files-SNAPSHOT</collaboration.version>
+      <collaboration.version>1.2.0-RC.1</collaboration.version>
    </properties>
    <dependencyManagement><dependencies>
       <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-bom-pom</artifactId><version>${qqq.version}</version><type>pom</type><scope>import</scope></dependency>
@@ -40,14 +40,14 @@
       <dependency><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-mobile-scanners-record-files</artifactId><version>${mobilerecordfiles.version}</version></dependency>
       <dependency><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-collaboration</artifactId><version>${collaboration.version}</version></dependency>
       <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-rdbms</artifactId></dependency>
-      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-frontend-next</artifactId><version>1.0.0-RC.35</version></dependency>
+      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-frontend-next</artifactId><version>1.0.0-RC.38</version></dependency>
       <dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><version>2.2.224</version></dependency>
       <dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-api</artifactId><version>6.0.2</version><scope>test</scope></dependency>
       <dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-engine</artifactId><version>6.0.2</version><scope>test</scope></dependency>
    </dependencies>
    <build><plugins>
       <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.13.0</version><configuration><showWarnings>true</showWarnings><failOnWarning>true</failOnWarning><proc>none</proc><compilerArgs><arg>-Xlint:deprecation</arg><arg>-Xlint:unchecked</arg><arg>-Werror</arg></compilerArgs></configuration></plugin>
-      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.2</version><configuration><systemPropertyVariables><qqq.logger.logSessionId.disabled>true</qqq.logger.logSessionId.disabled></systemPropertyVariables></configuration></plugin>
+      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.6</version><configuration><systemPropertyVariables><qqq.logger.logSessionId.disabled>true</qqq.logger.logSessionId.disabled></systemPropertyVariables></configuration></plugin>
       <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-dependency-plugin</artifactId><version>3.8.1</version></plugin>
       <plugin><groupId>org.codehaus.mojo</groupId><artifactId>exec-maven-plugin</artifactId><version>3.5.0</version><configuration><mainClass>com.kingsrook.examples.echo.demo.EchoDemo</mainClass></configuration></plugin>
       <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-checkstyle-plugin</artifactId><version>3.6.0</version><dependencies><dependency><groupId>com.puppycrawl.tools</groupId><artifactId>checkstyle</artifactId><version>14.3.0</version></dependency></dependencies><configuration><configLocation>${project.basedir}/../../../checkstyle/checkstyle.xml</configLocation><includeTestSourceDirectory>true</includeTestSourceDirectory><failOnViolation>true</failOnViolation><violationSeverity>warning</violationSeverity></configuration><executions><execution><phase>validate</phase><goals><goal>check</goal></goals></execution></executions></plugin>

examples/echo/demo/src/main/java/com/kingsrook/examples/echo/demo/EchoDemo.java

@@ -225,6 +225,11 @@ public class EchoDemo extends MobileScannersDemo implements AutoCloseable
       RecordFilesQBitConfig recordFiles = new RecordFilesQBitConfig().withBackendName(BACKEND)
          .withParentTables(List.of(EchoQBitProducer.SCAN_TABLE, MobileTestData.ORDERS, MobileTestData.ITEMS, MobileTestData.EVENTS))
          .withQuarantineGeneratedFiles(settings.releaseGeneratedFiles() ? Boolean.FALSE : null)
+         // Narrow, host-only opt-in: only CAPTURE intake with the verified approved-device identity from
+         // MobileCaptureIdentityProvider (JPEG/PNG, bounded; see EchoPhotoCapture.uploadConfiguration) is AVAILABLE
+         // on registration. quarantineNewFiles stays true for uploads, imports and attachment-panel files.
+         // Requires the Record Files version that contains withQuarantineCapturedFiles.
+         .withQuarantineCapturedFiles(Boolean.FALSE)
          .withDownloadConfiguration(new DownloadConfiguration("http://127.0.0.1:" + settings.port() + "/qqq/v1", 20 * 1024 * 1024, 2))
          .withUploadConfiguration(EchoPhotoCapture.uploadConfiguration());
       new RecordFilesQBitProducer().withQBitConfig(recordFiles).produce(instance);

examples/echo/demo/src/main/java/com/kingsrook/examples/echo/demo/EchoDemoAuthentication.java

@@ -22,7 +22,10 @@ import com.kingsrook.qqq.backend.core.model.session.QSession;
 /*******************************************************************************
  ** The existing demo password/session validation plus exactly the grants the
  ** owners' source requires. The validated account selects the role, never a
- ** request field. Printing and Record Files administration is granted to no one.
+ ** request field. Only the fixed admin account receives Printing administration,
+ ** template configure/publish and Record Files release (so approved scanner photos
+ ** can be released through the normal audited process); the scanner receives none
+ ** of them, and no one receives Record Files configure or review rights.
  *******************************************************************************/
 public class EchoDemoAuthentication extends DemoAuthenticationModule
 {
@@ -40,9 +43,10 @@ public class EchoDemoAuthentication extends DemoAuthenticationModule
    /**
     ** Admin also gets Printing's own administrator permission, which its native
     ** device pairing/approval/setup processes require, and what is needed to
-    ** prepare and publish templates. The scanner never receives these.
+    ** prepare and publish templates, and Record Files release for approved
+    ** captured photos. The scanner never receives these.
     */
-   static final List<String> ADMIN_ADDITIONS = List.of("printing_admin", "document-generation.configure", "document-generation.publish");
+   static final List<String> ADMIN_ADDITIONS = List.of("printing_admin", "document-generation.configure", "document-generation.publish", "record-files.release");
 
    private static volatile String tenant;
 

examples/echo/demo/src/main/java/com/kingsrook/examples/echo/demo/PrivateObjectFiles.java

@@ -30,12 +30,17 @@ import com.fasterxml.jackson.databind.ObjectMapper;
  ** file name, so no key can address another path, alias another object or climb
  ** out of the root. Objects are written to a temporary file in their own folder
  ** and linked into place, so a reader never sees a partial object and an existing
- ** object is never replaced.
+ ** object is never replaced. Publication is serialized within one JVM only; the
+ ** demo does not support several processes sharing one private root.
  *******************************************************************************/
 final class PrivateObjectFiles
 {
    private static final ObjectMapper JSON = new ObjectMapper();
    private static final int MAXIMUM_KEY = 2048;
+
+   // Guards final existence check, metadata publication and linking (and delete) across
+   // all instances in this JVM. The demo is a single process; this is not a cross-process lock.
+   private static final Object PUBLISH_LOCK = new Object();
    private final Path root;
 
 
@@ -68,7 +73,7 @@ final class PrivateObjectFiles
     ***************************************************************************/
    Path file(String bucket, String key)
    {
-      if(bucket == null || !bucket.matches("[A-Za-z0-9._-]{1,64}") || key == null || key.isEmpty() || key.length() > MAXIMUM_KEY)
+      if(bucket == null || !bucket.matches("[A-Za-z0-9._-]{1,64}") || bucket.equals(".") || bucket.equals("..") || key == null || key.isEmpty() || key.length() > MAXIMUM_KEY)
       {
          throw new IllegalArgumentException("Object bucket or key is outside policy");
       }
@@ -117,8 +122,7 @@ final class PrivateObjectFiles
             }
          }
          JSON.writeValue(sidecar.toFile(), metadata == null ? Map.of() : metadata);
-         Files.move(sidecar, metadataFile(target), StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
-         Files.createLink(target, temporary);
+         publish(target, temporary, sidecar);
       }
       finally
       {
@@ -129,6 +133,41 @@ final class PrivateObjectFiles
 
 
 
+   /***************************************************************************
+    ** Publish the metadata and then the object, as one step with respect to
+    ** other writers and deleters in this JVM. The lock is shared by every
+    ** instance, so two instances over the same root cannot interleave. It covers
+    ** only the final existence check and two cheap file operations, never the
+    ** copy of the content. A winner's metadata is therefore never replaced by a
+    ** loser's, and the metadata exists whenever the object does. This does not
+    ** coordinate separate processes.
+    ***************************************************************************/
+   private static void publish(Path target, Path temporary, Path sidecar) throws IOException
+   {
+      Path metadataFile = metadataFile(target);
+      synchronized(PUBLISH_LOCK)
+      {
+         if(Files.exists(target, java.nio.file.LinkOption.NOFOLLOW_LINKS))
+         {
+            throw new FileAlreadyExistsException("Object already exists");
+         }
+
+         // no object exists here, so any metadata is a stale leftover and may be replaced
+         Files.move(sidecar, metadataFile, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
+         try
+         {
+            Files.createLink(target, temporary);
+         }
+         catch(IOException | RuntimeException failure)
+         {
+            Files.deleteIfExists(metadataFile);
+            throw failure;
+         }
+      }
+   }
+
+
+
    /***************************************************************************
     ** Read an object's identity; absent means empty. Links are refused.
     ***************************************************************************/
@@ -162,8 +201,11 @@ final class PrivateObjectFiles
    void delete(String bucket, String key) throws IOException
    {
       Path target = file(bucket, key);
-      Files.deleteIfExists(target);
-      Files.deleteIfExists(metadataFile(target));
+      synchronized(PUBLISH_LOCK)
+      {
+         Files.deleteIfExists(target);
+         Files.deleteIfExists(metadataFile(target));
+      }
    }
 
 

examples/echo/demo/src/test/java/com/kingsrook/examples/echo/demo/EchoDemoAcceptanceTest.java

@@ -16,14 +16,21 @@ import java.net.http.HttpResponse;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.security.MessageDigest;
+import java.sql.Connection;
 import java.sql.DriverManager;
+import java.sql.Statement;
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Base64;
+import java.util.Comparator;
 import java.util.HashSet;
+import java.util.HexFormat;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.TreeMap;
 import java.util.UUID;
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.atomic.AtomicInteger;
@@ -34,6 +41,7 @@ import com.kingsrook.examples.echo.EchoTemplatePublisher;
 import com.kingsrook.qbits.documentgeneration.DocumentDefinitionService;
 import com.kingsrook.qbits.documentgeneration.DocumentGenerationQBitConfig;
 import com.kingsrook.qbits.documentgeneration.GenerationPorts;
+import com.kingsrook.qbits.recordfiles.RecordFilesTables;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
@@ -71,11 +79,17 @@ class EchoDemoAcceptanceTest
    private static final int RENDERER_CAP = 262144;
    private static final String CODE_VALUE = "001234567890";
    private static final String QR_VALUE = "QR-VALUE-0099";
+   /** EchoPermissions.checkPermissionsThrowing: the refusal for any actor without a currently approved scanner. */
+   private static final String ECHO_DEVICE_REFUSAL = "Echo requires an approved scanner and current Echo access.";
    private static final Set<Integer> PROTECTED = Set.of(57832, 51631, 18081, 18086, 18443, 19443, 18447, 18448, 18547, 18549, 18593);
 
    @TempDir
    Path root;
 
+   /** A second, separate temporary directory: the only place the snapshot is written to or read from. */
+   @TempDir
+   Path snapshotDirectory;
+
    private final HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).followRedirects(HttpClient.Redirect.NEVER).build();
    private String origin;
    private String deviceId;
@@ -823,6 +837,442 @@ class EchoDemoAcceptanceTest
 
 
 
+   /***************************************************************************
+    ** Everything a restore must give back exactly, read straight from the private
+    ** database and object directory rather than through the application.
+    ** retainedFiles are the Record Files owner's own rows (RecordFilesTables.FILE):
+    ** id, source table, source record, attachment, size.
+    ***************************************************************************/
+   private record Capture(List<List<String>> echoScans, List<List<String>> mobileScans, List<List<String>> retainedFiles, Map<String, String> objects)
+   {
+   }
+
+   /***************************************************************************
+    ** The status and error text of a refused request; see refusal().
+    ***************************************************************************/
+   private record Refusal(int status, String message)
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** Bounded backup/restore qualification of the composed host, on private
+    ** temporary paths only. A synthetic approved device scans an exact
+    ** leading-zero value through real HTTP and the real Record Files service
+    ** retains the generated original (the owner's retained-file row names the scan
+    ** as its source table and record). With every server stopped and the H2 files
+    ** closed, the database and object directory are copied together. A second scan
+    ** and file, a revocation and an ended session are then made, and only the two
+    ** temporary directories are restored. The restored state must equal the
+    ** snapshot and the later changes must be gone. The reverted approval is
+    ** trusted until the existing Revoke and End Session processes re-audit it,
+    ** after which a run opened before the revocation, and a new sign-in, are
+    ** refused by the host's own authorization. The renderer is controlled and the
+    ** printer is a database fixture: no job is printed, and no normal demo
+    ** database, service or external provider is touched. Retained files are read
+    ** from the owner's table, not through its service, and this does not qualify
+    ** production storage.
+    ***************************************************************************/
+   @Test
+   void restoredSnapshotKeepsScanAndRetainedFileAndRevertedApprovalStateIsReaudited() throws Exception
+   {
+      String scannerPassword = UUID.randomUUID().toString();
+      String adminPassword = UUID.randomUUID().toString();
+      String firstZpl = "^XA^FO48,48^FDcode128|" + CODE_VALUE + "^FS^XZ";
+      String secondZpl = "^XA^FO48,48^FDqr|" + QR_VALUE + "^FS^XZ";
+      String printerRowId;
+      Integer template;
+      String staleCookie;
+      String sessionId;
+      String firstEventId;
+      Capture atSnapshot;
+
+      // 1. Enroll, approve and scan through the real host; the original is retained by the real service.
+      int firstPort = freePort();
+      EchoDemoSettings first = new EchoDemoSettings(root, firstPort, TENANT, TOKEN, true, null, null);
+      origin = "http://127.0.0.1:" + firstPort;
+      try(EchoDemo demo = new EchoDemo(first, new ControlledRenderer(RENDERER_CAP), RENDERER_CAP))
+      {
+         demo.initializeDatabase(scannerPassword, adminPassword);
+         printerRowId = enrollPrinter(demo, first);
+         demo.start(firstPort);
+         String admin = login("admin", adminPassword);
+         staleCookie = login("scanner", scannerPassword);
+         template = publishTemplate(demo, printerRowId, admin, "Echo recovery label", MEDIA, REVISION, 101600, 152400, 300);
+         enrollAndApproveDevice(staleCookie, admin);
+         HttpResponse<String> heartbeat = request("POST", "/qqq/v1/qbit/mobile-scanners/sessions/heartbeat", staleCookie, "{\"foreground\":true,\"screenAvailable\":false}", true);
+         assertEquals(200, heartbeat.statusCode(), "The approved device must open a session.");
+         sessionId = new JSONObject(heartbeat.body()).getString("sessionId");
+         JSONObject firstEvent = event("LABEL-TYPE-CODE128", CODE_VALUE);
+         firstEventId = firstEvent.getString("eventId");
+         assertEquals("QUEUED", scanInNewRun(staleCookie, printerRowId, template, firstEvent).getString("printStatus"));
+         atSnapshot = capture(first);
+      }
+      finally
+      {
+         stopDatabase(first);
+      }
+      assertEquals(1, atSnapshot.echoScans().size());
+      List<String> scan = atSnapshot.echoScans().getFirst();
+      assertEquals(firstEventId, scan.get(1));
+      assertEquals(CODE_VALUE, scan.get(3), "The exact leading-zero text must be stored.");
+      assertEquals("LABEL-TYPE-CODE128", scan.get(4));
+      assertEquals("code128", scan.get(5));
+      assertEquals(1, atSnapshot.mobileScans().size());
+      assertEquals(scan.get(2), atSnapshot.mobileScans().getFirst().get(0), "The Echo scan must name its mobile scan.");
+      assertEquals(firstEventId, atSnapshot.mobileScans().getFirst().get(1));
+      assertEquals(CODE_VALUE, atSnapshot.mobileScans().getFirst().get(2));
+      assertEquals("scanner", atSnapshot.mobileScans().getFirst().get(3), "Attribution is derived by the server.");
+      assertEquals(deviceId, atSnapshot.mobileScans().getFirst().get(4));
+      assertEquals(Set.of(firstZpl), retainedOriginals(), "Record Files retained exactly the generated original.");
+      // the owner's retained-file row: source table and record are this exact scan, and the size is that of the original
+      assertEquals(1, atSnapshot.retainedFiles().size(), "Exactly one retained-file row exists for the one scan.");
+      List<String> file = atSnapshot.retainedFiles().getFirst();
+      assertEquals(EchoQBitProducer.SCAN_TABLE, file.get(1), "The retained file's source table is the Echo scan table.");
+      assertEquals(scan.get(0), file.get(2), "The retained file's source record is this exact scan.");
+      assertNotNull(file.get(3), "The retained file references its standard attachment.");
+      assertEquals(String.valueOf(firstZpl.length()), file.get(4), "The retained size is that of the generated original.");
+
+      // 2. Snapshot the closed database and the object directory together, into the other temporary directory.
+      takeSnapshot();
+
+      // 3. Change state after the snapshot, then stop.
+      int secondPort = freePort();
+      EchoDemoSettings second = new EchoDemoSettings(root, secondPort, TENANT, TOKEN, true, null, null);
+      origin = "http://127.0.0.1:" + secondPort;
+      try(EchoDemo demo = new EchoDemo(second, new ControlledRenderer(RENDERER_CAP), RENDERER_CAP))
+      {
+         demo.start(secondPort);
+         String admin = login("admin", adminPassword);
+         scanInNewRun(staleCookie, printerRowId, template, event("QRCODE", QR_VALUE));
+         runSelected("mobileDeviceRevoke", "mobileDevice", deviceId, new JSONObject(), admin);
+         runSelected("mobileSessionEnd", "mobileSession", sessionId, new JSONObject().put("reason", "post-snapshot change"), admin);
+         awaitSessionEnded(second, sessionId, staleCookie);
+         assertEquals(List.of(List.of("REVOKED")), sql(second, "SELECT status FROM mobileDevice WHERE id = '" + deviceId + "'", 1));
+         assertEquals(2, sql(second, "SELECT id FROM echo_scan", 1).size());
+         assertEquals(2, sql(second, "SELECT id FROM record_files_file", 1).size());
+         assertEquals(Set.of(firstZpl, secondZpl), retainedOriginals());
+      }
+      finally
+      {
+         stopDatabase(second);
+      }
+
+      // 4. Restore only the two temporary directories, then read them with no application running.
+      restoreSnapshot();
+      int thirdPort = freePort();
+      EchoDemoSettings third = new EchoDemoSettings(root, thirdPort, TENANT, TOKEN, true, null, null);
+      try
+      {
+         assertEquals(atSnapshot, capture(third), "The restored scan rows, retained-file row and object bytes must equal the snapshot.");
+         assertEquals(List.of(List.of("APPROVED")), sql(third, "SELECT status FROM mobileDevice WHERE id = '" + deviceId + "'", 1),
+            "The restore reverts the later revocation, so the device is approved again.");
+         assertEquals(List.of(List.of("ACTIVE")), sql(third, "SELECT status FROM mobileSession WHERE id = '" + sessionId + "'", 1),
+            "The restore reverts the later session end.");
+         assertEquals(1, sql(third, "SELECT id FROM demoSession WHERE id = '" + staleCookie + "'", 1).size(), "The earlier sign-in session is restored too.");
+         assertEquals(1, sql(third, "SELECT id FROM printing_job", 1).size());
+         assertEquals(Set.of(firstZpl), retainedOriginals(), "No object from after the snapshot may remain.");
+      }
+      finally
+      {
+         stopDatabase(third);
+      }
+
+      // 5. Restart on a new ephemeral port: the restored scan is served, stale authority works until re-audit, and then is refused.
+      ControlledRenderer renderer = new ControlledRenderer(RENDERER_CAP);
+      origin = "http://127.0.0.1:" + thirdPort;
+      try(EchoDemo demo = new EchoDemo(third, renderer, RENDERER_CAP))
+      {
+         demo.start(thirdPort);
+         JSONArray scans = query(EchoQBitProducer.SCAN_TABLE, staleCookie);
+         assertEquals(1, scans.length());
+         assertEquals(CODE_VALUE, scans.getJSONObject(0).getJSONObject("values").getString("barcode"));
+         HttpResponse<String> current = request("GET", "/qqq/v1/qbit/mobile-scanners/devices/current", staleCookie, null, true);
+         assertEquals(200, current.statusCode());
+         assertEquals("APPROVED", new JSONObject(current.body()).getString("status"), "Reopening without a re-audit would trust the reverted approval.");
+
+         // a real run, opened while the restored approval is still trusted and parked at its scan step
+         String run = openRun(staleCookie, printerRowId, template);
+         JSONObject lateScan = event("QRCODE", "STALE-SUBMIT-0001");
+
+         String admin = login("admin", adminPassword);
+         runSelected("mobileDeviceRevoke", "mobileDevice", deviceId, new JSONObject(), admin);
+         assertEquals(List.of(List.of("REVOKED")), sql(third, "SELECT status FROM mobileDevice WHERE id = '" + deviceId + "'", 1));
+         // the sign-in session is still valid, so this refusal is the host's device authorization, not authentication
+         assertEquals(200, request("GET", "/qqq/v1/qbit/mobile-scanners/devices/current", staleCookie, null, true).statusCode());
+         assertAuthorizationRefused(refusal(form("/qqq/v1/processes/echoPrint/" + run + "/step/scan", staleCookie, lateScan, true), staleCookie));
+         assertAuthorizationRefused(refusal(form("/qqq/v1/processes/echoPrint/init", staleCookie, new JSONObject(), true), staleCookie));
+
+         runSelected("mobileSessionEnd", "mobileSession", sessionId, new JSONObject().put("reason", "restore re-audit"), admin);
+         awaitSessionEnded(third, sessionId, staleCookie);
+         assertEquals(401, request("GET", "/qqq/v1/metaData", staleCookie, null, true).statusCode(), "The ended session must no longer authenticate.");
+         assertEquals(401, form("/qqq/v1/processes/echoPrint/" + run + "/step/scan", staleCookie, lateScan, true).statusCode(),
+            "The same run cannot be continued with the ended session.");
+
+         String freshCookie = login("scanner", scannerPassword);
+         assertAuthorizationRefused(refusal(form("/qqq/v1/processes/echoPrint/init", freshCookie, new JSONObject(), true), freshCookie));
+         assertEquals(0, renderer.renders.size(), "Nothing may be generated after the restore.");
+         assertEquals(1, sql(third, "SELECT id FROM echo_scan", 1).size());
+         assertEquals(1, sql(third, "SELECT id FROM mobileScan", 1).size());
+         assertEquals(1, sql(third, "SELECT id FROM printing_job", 1).size());
+         assertEquals(atSnapshot.objects(), objectHashes(), "Refused submissions must not change retained files.");
+      }
+      finally
+      {
+         stopDatabase(third);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** A new Echo run, then one scan in it, as the approved scanner device.
+    ***************************************************************************/
+   private JSONObject scanInNewRun(String scanner, String printerRowId, Integer template, JSONObject event) throws Exception
+   {
+      String process = openRun(scanner, printerRowId, template);
+      return echo(form("/qqq/v1/processes/echoPrint/" + process + "/step/scan", scanner, event, true), scanner).getJSONObject("values");
+   }
+
+
+
+   /***************************************************************************
+    ** A new Echo run chosen through setup, ready for its scan step.
+    ***************************************************************************/
+   private String openRun(String scanner, String printerRowId, Integer template) throws Exception
+   {
+      String process = echo(form("/qqq/v1/processes/echoPrint/init", scanner, new JSONObject(), true), scanner).getString("processUUID");
+      assertEquals("scan", echo(form("/qqq/v1/processes/echoPrint/" + process + "/step/setup", scanner,
+         new JSONObject().put("printerId", printerRowId).put("mediaId", MEDIA).put("templateId", template), true), scanner).getString("nextStep"));
+      return process;
+   }
+
+
+
+   /***************************************************************************
+    ** Run an existing administrator process on one selected record, from its
+    ** Actions menu, exactly as the browser and native client do.
+    ***************************************************************************/
+   private void runSelected(String process, String table, String recordId, JSONObject input, String admin) throws Exception
+   {
+      JSONObject selection = new JSONObject().put("recordsParam", "recordIds").put("recordIds", recordId).put("tableName", table);
+      JSONObject launched = complete(form("/qqq/v1/processes/" + process + "/init", admin, selection, false), process, admin, false);
+      assertEquals("input", launched.getString("nextStep"));
+      complete(form("/qqq/v1/processes/" + process + "/" + launched.getString("processUUID") + "/step/input", admin, input, false), process, admin, false);
+   }
+
+
+
+   /***************************************************************************
+    ** The End Session process commits the tombstone, then removes the stored
+    ** authentication session asynchronously; wait for both, within a bound.
+    ***************************************************************************/
+   private static void awaitSessionEnded(EchoDemoSettings settings, String sessionId, String cookie) throws Exception
+   {
+      long deadline = System.nanoTime() + Duration.ofSeconds(15).toNanos();
+      List<List<String>> state;
+      List<List<String>> remaining;
+      boolean done;
+      do
+      {
+         state = sql(settings, "SELECT status, authCleanupStatus FROM mobileSession WHERE id = '" + sessionId + "'", 2);
+         remaining = sql(settings, "SELECT id FROM demoSession WHERE id = '" + cookie + "'", 1);
+         done = List.of(List.of("ENDED", "REQUESTED")).equals(state) && remaining.isEmpty();
+         if(!done)
+         {
+            Thread.sleep(50);
+         }
+      }
+      while(!done && System.nanoTime() < deadline);
+      assertEquals(List.of(List.of("ENDED", "REQUESTED")), state, "The session must be ended with cleanup requested.");
+      assertTrue(remaining.isEmpty(), "The stored authentication session must be removed.");
+   }
+
+
+
+   /***************************************************************************
+    ** Follow an Echo process request to its outcome: the immediate HTTP status,
+    ** or, when the step went asynchronous, the final status body. Returns the
+    ** HTTP status and the "error" text, with no assertion about either.
+    ***************************************************************************/
+   private Refusal refusal(HttpResponse<String> response, String cookie) throws Exception
+   {
+      long deadline = System.nanoTime() + Duration.ofSeconds(30).toNanos();
+      JSONObject body = new JSONObject(response.body());
+      while(response.statusCode() == 200 && ("JOB_STARTED".equals(body.optString("type")) || "RUNNING".equals(body.optString("type"))))
+      {
+         assertTrue(System.nanoTime() < deadline, "Native process timed out.");
+         Thread.sleep(25);
+         response = request("GET", "/qqq/v1/processes/" + EchoQBitProducer.PROCESS + "/" + body.getString("processUUID") + "/status/" + body.getString("jobUUID"), cookie, null, true);
+         body = new JSONObject(response.body());
+      }
+      return new Refusal(response.statusCode(), body.optString("error"));
+   }
+
+
+
+   /***************************************************************************
+    ** The exact refusal of a revoked device under a still-valid sign-in: the
+    ** Echo process permission checker's own message (EchoPermissions), as a 403
+    ** or as the process error, and never a success or any other failure.
+    ***************************************************************************/
+   private static void assertAuthorizationRefused(Refusal refusal)
+   {
+      assertTrue(refusal.status() == 403 || refusal.status() == 200, "Unexpected status " + refusal.status() + ": " + refusal.message());
+      assertEquals(ECHO_DEVICE_REFUSAL, refusal.message(), "The refusal must be Echo's own device authorization message.");
+   }
+
+
+
+   /***************************************************************************
+    ** Read the durable state straight from the closed-to-the-app database and
+    ** the object directory.
+    ***************************************************************************/
+   private Capture capture(EchoDemoSettings settings) throws Exception
+   {
+      List<List<String>> echoScans = sql(settings, "SELECT id, eventId, mobileScanId, barcode, symbology, rendererSymbology, printJobId, state FROM echo_scan ORDER BY id", 8);
+      List<List<String>> mobileScans = sql(settings, "SELECT id, eventId, barcode, userId, deviceId FROM mobileScan ORDER BY id", 5);
+      List<List<String>> retainedFiles = sql(settings, "SELECT id, table_name, record_id, attachment_id, size_bytes FROM " + RecordFilesTables.FILE + " ORDER BY id", 5);
+      return new Capture(echoScans, mobileScans, retainedFiles, objectHashes());
+   }
+
+
+
+   /***************************************************************************
+    ** The SHA-256 of every file under the object directory, by relative path,
+    ** including each object's metadata file.
+    ***************************************************************************/
+   private Map<String, String> objectHashes() throws Exception
+   {
+      Path objects = root.resolve("objects");
+      Map<String, String> hashes = new TreeMap<>();
+      try(Stream<Path> files = Files.walk(objects))
+      {
+         for(Path file : files.filter(Files::isRegularFile).toList())
+         {
+            hashes.put(objects.relativize(file).toString().replace('\\', '/'), HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(Files.readAllBytes(file))));
+         }
+      }
+      return hashes;
+   }
+
+
+
+   /***************************************************************************
+    ** The content of every retained original (an object that is not metadata).
+    ***************************************************************************/
+   private Set<String> retainedOriginals() throws Exception
+   {
+      Set<String> retained = new HashSet<>();
+      try(Stream<Path> files = Files.walk(root.resolve("objects")))
+      {
+         for(Path file : files.filter(Files::isRegularFile).filter(path -> !path.getFileName().toString().endsWith(".json")).toList())
+         {
+            retained.add(Files.readString(file, StandardCharsets.US_ASCII));
+         }
+      }
+      return retained;
+   }
+
+
+
+   /***************************************************************************
+    ** Close the private file database so its files are complete and unlocked.
+    ** The server is already stopped when this runs.
+    ***************************************************************************/
+   private static void stopDatabase(EchoDemoSettings settings) throws Exception
+   {
+      QContext.clear();
+      try(Connection connection = DriverManager.getConnection(EchoDemo.jdbcUrl(settings), "sa", ""); Statement statement = connection.createStatement())
+      {
+         statement.execute("SHUTDOWN");
+      }
+      com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager.resetConnectionProviders();
+   }
+
+
+
+   /***************************************************************************
+    ** Copy the closed database and object directory, together, to the snapshot
+    ** directory.
+    ***************************************************************************/
+   private void takeSnapshot() throws Exception
+   {
+      for(String name : List.of("db", "objects"))
+      {
+         copyTree(root.resolve(name), snapshotDirectory.resolve(name));
+      }
+      try(Stream<Path> files = Files.list(snapshotDirectory.resolve("db")))
+      {
+         List<String> names = files.map(path -> path.getFileName().toString()).toList();
+         assertTrue(names.stream().anyMatch(name -> name.endsWith(".mv.db")), "The snapshot must contain the database file: " + names);
+         assertFalse(names.stream().anyMatch(name -> name.endsWith(".lock.db")), "The database must be closed before the snapshot.");
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Replace only this test's database and object directories from the snapshot.
+    ***************************************************************************/
+   private void restoreSnapshot() throws Exception
+   {
+      Path liveRoot = root.toAbsolutePath().normalize();
+      Path snapshotRoot = snapshotDirectory.toAbsolutePath().normalize();
+      assertFalse(snapshotRoot.startsWith(liveRoot) || liveRoot.startsWith(snapshotRoot), "The two temporary directories must be separate.");
+      for(String name : List.of("db", "objects"))
+      {
+         Path live = liveRoot.resolve(name).normalize();
+         assertTrue(live.startsWith(liveRoot), "Only paths inside this test's temporary directory may be replaced.");
+         assertTrue(Files.isDirectory(snapshotRoot.resolve(name)));
+         deleteTree(live);
+         copyTree(snapshotRoot.resolve(name), live);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Copy a directory tree, creating directories and preserving file times.
+    ***************************************************************************/
+   private static void copyTree(Path from, Path to) throws Exception
+   {
+      try(Stream<Path> paths = Files.walk(from))
+      {
+         for(Path source : paths.toList())
+         {
+            Path target = to.resolve(from.relativize(source).toString());
+            if(Files.isDirectory(source))
+            {
+               Files.createDirectories(target);
+            }
+            else
+            {
+               Files.copy(source, target, StandardCopyOption.COPY_ATTRIBUTES);
+            }
+         }
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Delete a directory tree, children first.
+    ***************************************************************************/
+   private static void deleteTree(Path tree) throws Exception
+   {
+      try(Stream<Path> paths = Files.walk(tree))
+      {
+         for(Path path : paths.sorted(Comparator.reverseOrder()).toList())
+         {
+            Files.delete(path);
+         }
+      }
+   }
+
+
+
    /***************************************************************************
     ** One scan event with a unique id and the exact scanned text.
     ***************************************************************************/

examples/echo/demo/src/test/java/com/kingsrook/examples/echo/demo/EchoDemoSettingsTest.java

@@ -111,7 +111,7 @@ class EchoDemoSettingsTest
    {
       assertEquals(List.of("echo.use", "printing_operator", "document-generation.view", "document-generation.generate", "document-generation.print",
          "record-files.view", "record-files.manage", "echoScan.attach", "testOrder.attach", "testOrderItem.attach", "testOrderEvent.attach"), EchoDemoAuthentication.SCANNER);
-      assertEquals(List.of("printing_admin", "document-generation.configure", "document-generation.publish"), EchoDemoAuthentication.ADMIN_ADDITIONS);
-      assertFalse(EchoDemoAuthentication.SCANNER.stream().anyMatch(name -> name.endsWith(".configure") || name.endsWith(".publish") || name.endsWith("admin")));
+      assertEquals(List.of("printing_admin", "document-generation.configure", "document-generation.publish", "record-files.release"), EchoDemoAuthentication.ADMIN_ADDITIONS);
+      assertFalse(EchoDemoAuthentication.SCANNER.stream().anyMatch(name -> name.endsWith(".configure") || name.endsWith(".publish") || name.endsWith("admin") || name.endsWith(".release")));
    }
 }

examples/echo/demo/src/test/java/com/kingsrook/examples/echo/demo/EchoDemoStartupTest.java

@@ -179,6 +179,12 @@ class EchoDemoStartupTest
          assertFalse(scanner.hasPermission("printing_admin") || scanner.hasPermission("document-generation.publish"));
          assertTrue(admin.hasPermission("printing_admin") && admin.hasPermission("document-generation.publish"));
          assertFalse(stranger.hasPermission("echo.use") || stranger.hasPermission("printing_operator"));
+         assertTrue(admin.hasPermission("record-files.release"));
+         assertFalse(scanner.hasPermission("record-files.release") || stranger.hasPermission("record-files.release"));
+         assertFalse(admin.hasPermission("record-files.configure") || admin.hasPermission("record-files.review"));
+         // Revalidation keeps the role derived from the validated user, never widening or dropping it.
+         assertTrue(EchoDemoAuthentication.grant(instance, admin).hasPermission("record-files.release"));
+         assertFalse(EchoDemoAuthentication.grant(instance, scanner).hasPermission("record-files.release"));
 
          HttpResponse<String> version = send(port, "/printing/v1/version", null, null);
          assertEquals(200, version.statusCode());

examples/echo/demo/src/test/java/com/kingsrook/examples/echo/demo/EchoPhotoCaptureTest.java

@@ -171,6 +171,9 @@ class EchoPhotoCaptureTest
             .filter(RecordFilesQBitConfig.class::isInstance).findFirst().orElseThrow();
          assertEquals(List.of(EchoQBitProducer.SCAN_TABLE, MobileTestData.ORDERS, MobileTestData.ITEMS, MobileTestData.EVENTS), config.getParentTables());
          assertEquals(Set.of("image/jpeg", "image/png"), config.getUploadConfiguration().limits().acceptedMediaTypes());
+         assertEquals(Boolean.FALSE, config.getQuarantineCapturedFiles(), "approved-device captures are admitted immediately");
+         assertEquals(Boolean.TRUE, config.getQuarantineNewFiles(), "every other origin keeps the quarantine default");
+         assertNull(config.getQuarantineGeneratedFiles(), "the generated-output policy is unchanged");
          assertTrue(config.getUploadConfiguration().createIdentityProvider() instanceof MobileCaptureIdentityProvider);
          assertTrue(config.getUploadConfiguration().createStorage() instanceof LocalStagingChunkStorage);
 

examples/echo/demo/src/test/java/com/kingsrook/examples/echo/demo/PrivateObjectFilesTest.java

@@ -8,16 +8,24 @@ package com.kingsrook.examples.echo.demo;
 
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
+import java.io.InputStream;
 import java.nio.file.FileAlreadyExistsException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
 import java.util.stream.Stream;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -109,6 +117,147 @@ class PrivateObjectFilesTest
 
 
 
+   /***************************************************************************
+    ** Dot path segments are not buckets; ordinary names containing dots are.
+    ***************************************************************************/
+   @Test
+   void dotBucketsAreRefusedAndValidBucketsStillWork() throws IOException
+   {
+      PrivateObjectFiles files = new PrivateObjectFiles(root);
+      assertThrows(IllegalArgumentException.class, () -> files.file(".", "k"));
+      assertThrows(IllegalArgumentException.class, () -> files.file("..", "k"));
+      assertThrows(IllegalArgumentException.class, () -> files.create("..", "k", bytes("x"), 1024, Map.of()));
+
+      assertTrue(files.file("canonical", "k").normalize().startsWith(root.resolve("canonical")));
+      assertTrue(files.file("a.b-c_d", "k").normalize().startsWith(root.resolve("a.b-c_d")));
+      assertTrue(files.file("..x", "k").normalize().startsWith(root.resolve("..x")));
+      files.create("canonical", "k", bytes("ok"), 1024, Map.of("a", "b"));
+      assertEquals(Map.of("a", "b"), files.find("canonical", "k").orElseThrow().metadata());
+   }
+
+
+
+   /***************************************************************************
+    ** A stream that, on its first read, reports that its writer is inside the
+    ** write path and then waits until the test releases that writer.
+    ***************************************************************************/
+   private static InputStream gated(String value, CountDownLatch entered, CountDownLatch release)
+   {
+      ByteArrayInputStream delegate = bytes(value);
+      return new InputStream()
+      {
+         private boolean first = true;
+
+
+
+         @Override
+         public int read() throws IOException
+         {
+            gate();
+            return delegate.read();
+         }
+
+
+
+         @Override
+         public int read(byte[] buffer, int offset, int length) throws IOException
+         {
+            gate();
+            return delegate.read(buffer, offset, length);
+         }
+
+
+
+         private void gate() throws IOException
+         {
+            if(first)
+            {
+               first = false;
+               entered.countDown();
+               try
+               {
+                  if(!release.await(30, TimeUnit.SECONDS))
+                  {
+                     throw new IOException("Test writer was never released");
+                  }
+               }
+               catch(InterruptedException failure)
+               {
+                  Thread.currentThread().interrupt();
+                  throw new IOException(failure);
+               }
+            }
+         }
+      };
+   }
+
+
+
+   /***************************************************************************
+    ** Two adapters over one root write the same key with different bytes and
+    ** metadata. Both pass the initial existence check and block in their streams;
+    ** the first is released and completes, then the second is released and must
+    ** be refused at the final existence check without touching the first's
+    ** bytes or metadata (the old code replaced the metadata before failing).
+    ***************************************************************************/
+   @Test
+   void lateSecondWriterIsRefusedAndFirstWritersBytesAndMetadataRemain() throws Exception
+   {
+      PrivateObjectFiles first = new PrivateObjectFiles(root);
+      PrivateObjectFiles second = new PrivateObjectFiles(root);
+      CountDownLatch enteredOne = new CountDownLatch(1);
+      CountDownLatch enteredTwo = new CountDownLatch(1);
+      CountDownLatch releaseOne = new CountDownLatch(1);
+      CountDownLatch releaseTwo = new CountDownLatch(1);
+      ExecutorService executor = Executors.newFixedThreadPool(2);
+      try
+      {
+         Future<?> one = executor.submit(() ->
+         {
+            first.create("canonical", "same", gated("content-from-one", enteredOne, releaseOne), 1024, Map.of("writer", "one"));
+            return null;
+         });
+         Future<?> two = executor.submit(() ->
+         {
+            second.create("canonical", "same", gated("content-from-two-longer", enteredTwo, releaseTwo), 1024, Map.of("writer", "two"));
+            return null;
+         });
+
+         // both writers are past their initial existence check and blocked in their streams
+         assertTrue(enteredOne.await(30, TimeUnit.SECONDS), "first writer should enter the write path");
+         assertTrue(enteredTwo.await(30, TimeUnit.SECONDS), "second writer should enter the write path");
+
+         // first finishes completely while second stays blocked
+         releaseOne.countDown();
+         one.get(30, TimeUnit.SECONDS);
+         assertFalse(two.isDone(), "second writer must still be blocked in its stream");
+
+         // second now reaches publication with an object already in place and must refuse
+         releaseTwo.countDown();
+         ExecutionException failure = assertThrows(ExecutionException.class, () -> two.get(30, TimeUnit.SECONDS));
+         assertInstanceOf(FileAlreadyExistsException.class, failure.getCause());
+
+         var stored = first.find("canonical", "same").orElseThrow();
+         assertEquals("content-from-one", Files.readString(stored.file()));
+         assertEquals(Map.of("writer", "one"), stored.metadata());
+         assertEquals(stored.metadata(), second.find("canonical", "same").orElseThrow().metadata());
+      }
+      finally
+      {
+         releaseOne.countDown();
+         releaseTwo.countDown();
+         executor.shutdownNow();
+         assertTrue(executor.awaitTermination(30, TimeUnit.SECONDS));
+      }
+
+      try(Stream<Path> all = Files.walk(root))
+      {
+         assertFalse(all.anyMatch(path -> path.getFileName().toString().startsWith(".incoming-")));
+      }
+   }
+
+
+
    /***************************************************************************
     ** Delete removes the object and its metadata; absent is not an error.
     ***************************************************************************/

examples/echo/pom.xml

@@ -16,15 +16,15 @@
    <properties>
       <maven.compiler.release>21</maven.compiler.release>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-      <qqq.version>4.1.0-RC.21</qqq.version>
+      <qqq.version>4.1.0-RC.26</qqq.version>
       <mobile.version>0.1.0-SNAPSHOT</mobile.version>
       <!-- Echo's copies per scan needs a Generation build with the print-copies change (appended copies on
            DocumentGenerationService.Request and GenerationPorts.PrintRequest, supportsCopies on the printing bridge,
            migration 20261102-print-copies-h2.sql). Printing 1.0.0 is released and qualified; only the Generation
            cohort still needs a coherent published input. Until that is published at this coordinate, override
            generation.version with a coherent build that has it; no private build is named here. -->
-      <generation.version>0.1.0-SNAPSHOT</generation.version>
-      <printing.version>1.0.0</printing.version>
+      <generation.version>1.1.0-RC.1</generation.version>
+      <printing.version>1.2.0-RC.1</printing.version>
    </properties>
    <dependencyManagement><dependencies>
       <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-bom-pom</artifactId><version>${qqq.version}</version><type>pom</type><scope>import</scope></dependency>
@@ -37,14 +37,15 @@
       <dependency><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-generation-record-files</artifactId><version>${generation.version}</version></dependency>
       <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-rdbms</artifactId></dependency>
       <dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><version>2.2.224</version><scope>test</scope></dependency>
+      <dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId><version>42.7.8</version><scope>test</scope></dependency>
       <dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-api</artifactId><version>6.0.2</version><scope>test</scope></dependency>
       <dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-engine</artifactId><version>6.0.2</version><scope>test</scope></dependency>
-      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-frontend-next</artifactId><version>1.0.0-RC.35</version><scope>test</scope></dependency>
+      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-frontend-next</artifactId><version>1.0.0-RC.38</version><scope>test</scope></dependency>
       <dependency><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-mobile-scanners-demo</artifactId><version>${mobile.version}</version><scope>test</scope></dependency>
    </dependencies>
    <build><resources><resource><directory>src/main/resources</directory><filtering>false</filtering></resource><resource><directory>${project.basedir}/../..</directory><filtering>false</filtering><includes><include>LICENSE</include><include>NOTICE</include></includes><targetPath>META-INF/qqq-echo</targetPath></resource></resources><plugins>
       <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.13.0</version><configuration><showWarnings>true</showWarnings><failOnWarning>true</failOnWarning><proc>none</proc><compilerArgs><arg>-Xlint:deprecation</arg><arg>-Xlint:unchecked</arg><arg>-Werror</arg></compilerArgs></configuration></plugin>
-      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.2</version></plugin>
+      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.6</version></plugin>
       <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-checkstyle-plugin</artifactId><version>3.6.0</version><dependencies><dependency><groupId>com.puppycrawl.tools</groupId><artifactId>checkstyle</artifactId><version>14.3.0</version></dependency></dependencies><configuration><configLocation>${project.basedir}/../../checkstyle/checkstyle.xml</configLocation><includeTestSourceDirectory>true</includeTestSourceDirectory><failOnViolation>true</failOnViolation><violationSeverity>warning</violationSeverity></configuration><executions><execution><phase>validate</phase><goals><goal>check</goal></goals></execution></executions></plugin>
    </plugins></build>
 </project>

examples/echo/src/main/java/com/kingsrook/examples/echo/EchoPermissions.java

@@ -10,10 +10,14 @@ import com.kingsrook.qqq.backend.core.actions.permissions.CustomPermissionChecke
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput;
+import com.kingsrook.qqq.backend.core.model.actions.metadata.ProcessMetaDataInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 
 
 /*******************************************************************************
@@ -35,7 +39,13 @@ public final class EchoPermissions implements CustomPermissionChecker
          {
             throw new QPermissionDeniedException("Echo access is required; direct state writes are not allowed.");
          }
-         EchoConfig.current().identities.current();
+         // Browsing the application performs no scan or print operation.
+         // Process execution, widget and record access still require approved device authority.
+         boolean processDiscovery = metadata instanceof QProcessMetaData && (action instanceof MetaDataInput || action instanceof ProcessMetaDataInput);
+         if(!(metadata instanceof QAppMetaData) && !processDiscovery)
+         {
+            EchoConfig.current().identities.current();
+         }
       }
       catch(Exception failure)
       {
@@ -43,3 +53,4 @@ public final class EchoPermissions implements CustomPermissionChecker
       }
    }
 }
+

examples/echo/src/main/java/com/kingsrook/examples/echo/EchoPrintingDestinations.java

@@ -118,7 +118,7 @@ public final class EchoPrintingDestinations implements EchoDestinations
       String refusal = refusal(current.mode(), scan);
       if(refusal != null)
       {
-         throw new QException(refusal);
+         throw new EchoScanRejected(refusal);
       }
       return current.plan();
    }
@@ -274,7 +274,8 @@ public final class EchoPrintingDestinations implements EchoDestinations
       for(Object item : scene.getJSONArray("elements"))
       {
          JSONObject text = (JSONObject) item;
-         if("text".equals(text.optString("type")) && "/record/humanReadable".equals(text.optString("valuePath"))
+         if(("text".equals(text.optString("type")) || "rasterText".equals(text.optString("type")))
+            && "/record/humanReadable".equals(text.optString("valuePath"))
             && text.optInt("y", -1) > barcode.optInt("y", -1))
          {
             return true;
@@ -293,15 +294,15 @@ public final class EchoPrintingDestinations implements EchoDestinations
    {
       if((mode == SceneMode.GS1) != "gs1-128".equals(scan.rendererSymbology()))
       {
-         return "GS1-128 scans require the GS1-128 document; that document accepts only GS1-128. Leave Echo and choose the matching document; no print was requested.";
+         return "GS1-128 scans require the GS1-128 document; that document accepts only GS1-128. No print was requested. Scan a barcode matching the selected document.";
       }
       if(mode == SceneMode.PLAIN && EchoTemplates.SCANNER_SYMBOLOGIES.contains(scan.rendererSymbology()))
       {
-         return "EAN and UPC need the scanner-fidelity document. Leave Echo and choose it; no print was requested.";
+         return "EAN and UPC need the scanner-fidelity document. No print was requested. Scan a barcode matching the selected document.";
       }
       if(mode == SceneMode.SCANNER && scan.aimIdentifier() == null)
       {
-         return "The scanner-fidelity document needs the scanner's AIM identifier and this scan has none. Leave Echo and choose the plain document; no print was requested.";
+         return "The scanner-fidelity document needs the scanner's AIM identifier and this scan has none. No print was requested. Scan a barcode with its AIM identifier.";
       }
       return null;
    }
@@ -349,8 +350,7 @@ public final class EchoPrintingDestinations implements EchoDestinations
          for(Object item : new JSONArray(mediaProfilesJson == null ? "[]" : mediaProfilesJson))
          {
             PrintingMediaProfile profile = PrintingMediaProfile.parse((JSONObject) item);
-            choices.add(new MediaChoice(profile.id(), profile.name() + " (" + String.format(Locale.ROOT, "%.1f x %.1f mm, %d dpi",
-               profile.widthMicrons() / 1000.0, profile.heightMicrons() / 1000.0, profile.dpiX()) + ")"));
+            choices.add(new MediaChoice(profile.id(), mediaLabel(profile)));
          }
       }
       catch(RuntimeException failure)
@@ -362,6 +362,26 @@ public final class EchoPrintingDestinations implements EchoDestinations
 
 
 
+   /***************************************************************************
+    ** Prefer exact quarter-inch stock sizes; other stock retains metric units.
+    ** Keep meaningful printer names without repeating a dimensions-only name.
+    ***************************************************************************/
+   private static String mediaLabel(PrintingMediaProfile profile)
+   {
+      boolean inches = profile.widthMicrons() % 6350 == 0 && profile.heightMicrons() % 6350 == 0;
+      int divisor = inches ? 25400 : 1000;
+      String width = java.math.BigDecimal.valueOf(profile.widthMicrons()).divide(java.math.BigDecimal.valueOf(divisor)).stripTrailingZeros().toPlainString();
+      String height = java.math.BigDecimal.valueOf(profile.heightMicrons()).divide(java.math.BigDecimal.valueOf(divisor)).stripTrailingZeros().toPlainString();
+      String resolution = profile.dpiX() == profile.dpiY() ? String.valueOf(profile.dpiX()) : profile.dpiX() + " × " + profile.dpiY();
+      String name = profile.name().strip();
+      String remainder = name.toLowerCase(Locale.ROOT).replaceAll("\\b(inches|inch|in|mm|label|paper|dpi)\\b", "")
+         .replaceAll("[\\s0-9.,x×()·-]+", "");
+      boolean generic = remainder.isBlank() || List.of("custom", "default", "media", "userdefined", "windowsqueuedefault").contains(remainder);
+      return (generic ? "" : name + " · ") + width + " × " + height + (inches ? " in label · " : " mm label · ") + resolution + " dpi";
+   }
+
+
+
    /***************************************************************************
     ** Select one reported media profile by identity; never guess dimensions.
     ***************************************************************************/

examples/echo/src/main/java/com/kingsrook/examples/echo/EchoQBitProducer.java

@@ -19,6 +19,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.ValueRangeBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 import com.kingsrook.qqq.backend.core.model.metadata.permissions.PermissionLevel;
 import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
 import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
@@ -87,7 +88,7 @@ public final class EchoQBitProducer
       instance.addTable(scan);
       instance.addWidget(new QWidgetMetaData().withName(WIDGET).withType("composite").withLabel("Echo barcode scanner")
          .withCodeReference(new QCodeReference(EchoWidget.class)).withPermissionRules(rules()));
-      instance.addProcess(new QProcessMetaData().withName(PROCESS).withLabel("Echo — scan to print").withPermissionRules(rules())
+      instance.addProcess(new QProcessMetaData().withName(PROCESS).withLabel("Echo Printing").withIcon(new QIcon().withName("account_tree")).withPermissionRules(rules())
          .withCancelStep(new QBackendStepMetaData().withName("cancel").withCode(new QCodeReference(EchoSteps.Cancel.class)))
          .withStep(new QBackendStepMetaData().withName("begin").withCode(new QCodeReference(EchoSteps.Begin.class)))
          .withStep(new QFrontendStepMetaData().withName("setup").withLabel("Choose printer, paper or label, and document")

examples/echo/src/main/java/com/kingsrook/examples/echo/EchoScanRejected.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2026 Kingsrook, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package com.kingsrook.examples.echo;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+
+
+/*******************************************************************************
+ ** Only deterministic pre-print barcode/document incompatibility uses this type.
+ *******************************************************************************/
+final class EchoScanRejected extends QException
+{
+   /***************************************************************************
+    ** The message contains guidance, never a scanned payload.
+    ***************************************************************************/
+   EchoScanRejected(String message)
+   {
+      super(message);
+   }
+}

examples/echo/src/main/java/com/kingsrook/examples/echo/EchoService.java

@@ -175,12 +175,21 @@ public final class EchoService
    {
       requireText(runId, 36);
       MobileDeviceAuthorization.Identity identity = identity();
-      Scan scan = Scan.from(context);
-      if(!identity.actorId().equals(context.get("userId")) || !identity.deviceId().equals(context.get("deviceId"))
+      if(context == null || !identity.actorId().equals(context.get("userId")) || !identity.deviceId().equals(context.get("deviceId"))
          || !EchoQBitProducer.APP.equals(context.get("appId")) || !EchoQBitProducer.PROCESS.equals(context.get("processName")))
       {
          throw new QException("Scan context does not match this approved scanner sign-in.");
       }
+      Scan scan;
+      try
+      {
+         scan = Scan.from(context);
+      }
+      catch(EchoScanRejected rejection)
+      {
+         store.requireUnadmitted(runId, identity, requireText(context.get("scanId"), 64), claimedCopies);
+         throw rejection;
+      }
       EchoStore.Admission admission = store.claim(runId, identity, scan, claimedCopies);
       if(admission.acceptedJob() != null)
       {
@@ -215,7 +224,16 @@ public final class EchoService
          {
             throw new QException("This Echo run has no chosen document. Leave Echo and choose again.");
          }
-         EchoDestinations.Plan plan = destinations.plan(identity, destination, admission.document(), scan);
+         EchoDestinations.Plan plan;
+         try
+         {
+            plan = destinations.plan(identity, destination, admission.document(), scan);
+         }
+         catch(EchoScanRejected rejection)
+         {
+            store.reject(runId, admission.scanId(), scan.eventId());
+            throw rejection;
+         }
          if(plan == null || plan.templateId() == null || plan.templateId() < 1 || plan.templateRevisionId() == null || plan.templateRevisionId() < 1
             || plan.format() == null || !stockMatches(plan.stock(), destination))
          {
@@ -375,7 +393,7 @@ public final class EchoService
             case "EAN8", "LABEL-TYPE-EAN8" -> "ean8";
             case "UPCA", "LABEL-TYPE-UPCA" -> "upca";
             case "UPCE0", "LABEL-TYPE-UPCE0" -> "upce";
-            default -> throw new QException("This barcode type cannot yet be reproduced faithfully by Echo. No print was requested.");
+            default -> throw new EchoScanRejected("This barcode type cannot yet be reproduced faithfully by Echo. No print was requested.");
          };
          ///////////////////////////////////////////////////////////////////////////////////////
          // the qualified first-physical profile is printable ASCII 0x20..0x7E for all types; //
@@ -385,11 +403,18 @@ public final class EchoService
          if(gs1)
          {
             renderer = "gs1-128";
-            EchoGs1.parse(value);
+            try
+            {
+               EchoGs1.parse(value);
+            }
+            catch(QException invalidGs1)
+            {
+               throw new EchoScanRejected(invalidGs1.getMessage());
+            }
          }
          else if("gs1-128".equals(renderer) || value.chars().anyMatch(character -> character < 0x20 || character > 0x7E))
          {
-            throw new QException("This scan needs control/binary/GS1 or non-ASCII payload handling that Echo has not qualified; only printable ASCII is supported. No print was requested.");
+            throw new EchoScanRejected("This scan needs control/binary/GS1 or non-ASCII payload handling that Echo has not qualified; only printable ASCII is supported. No print was requested.");
          }
          String aim = requireFidelityMetadata(context, renderer, value);
          return new Scan(event, value, type, renderer, source, captured, mobileScan, received, aim);
@@ -409,23 +434,23 @@ public final class EchoService
          boolean gs1 = "gs1-128".equals(renderer);
          if(aim != null && !(gs1 ? "]C1" : PLAIN_AIM.get(renderer)).equals(aim))
          {
-            throw new QException("This scan reports a barcode mode (GS1, ECI, structured or full-ASCII) that Echo cannot reproduce faithfully. No print was requested.");
+            throw new EchoScanRejected("This scan reports a barcode mode (GS1, ECI, structured or full-ASCII) that Echo cannot reproduce faithfully. No print was requested.");
          }
          if(EchoTemplates.SCANNER_SYMBOLOGIES.contains(renderer))
          {
             if(aim == null)
             {
-               throw new QException("EAN and UPC need the scanner's AIM identifier to be reproduced faithfully, and this scan has none. No print was requested.");
+               throw new EchoScanRejected("EAN and UPC need the scanner's AIM identifier to be reproduced faithfully, and this scan has none. No print was requested.");
             }
             if(!validRetailValue(renderer, value))
             {
-               throw new QException("This EAN or UPC value has the wrong length, number system or check digit. No print was requested.");
+               throw new EchoScanRejected("This EAN or UPC value has the wrong length, number system or check digit. No print was requested.");
             }
          }
          Object raw = context.get("rawDataBase64");
          if(gs1 && raw == null)
          {
-            throw new QException("GS1-128 duplication needs the scanner's original raw bytes and AIM identifier. No print was requested.");
+            throw new EchoScanRejected("GS1-128 duplication needs the scanner's original raw bytes and AIM identifier. No print was requested.");
          }
          if(raw != null)
          {

examples/echo/src/main/java/com/kingsrook/examples/echo/EchoSteps.java

@@ -93,12 +93,16 @@ public final class EchoSteps
       public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
       {
          String run = null;
+         java.util.Map<String, java.io.Serializable> context = null;
          try
          {
             run = boundRun(input, output);
             Integer claimed = copies(input.getValue("copies"));
-            var context = MobileScannerActions.capture(input, EchoQBitProducer.APP);
+            context = MobileScannerActions.capture(input, EchoQBitProducer.APP);
             EchoService.Acceptance accepted = EchoConfig.current().service.print(run, context, claimed);
+            output.addValue("scanRejected", false);
+            output.addValue("rejectedEventId", null);
+            output.addValue("rejectionMessage", null);
             output.addValue("scanContext", new HashMap<>(context));
             output.addValue("scanId", context.get("scanId"));
             output.addValue("echoScanId", accepted.scanId());
@@ -110,6 +114,19 @@ public final class EchoSteps
             output.addValue(EchoQBitProducer.WIDGET, new EchoWidget.Data(accepted.copies()));
             output.getProcessState().setNextStepName("scan");
          }
+         catch(EchoScanRejected rejection)
+         {
+            output.addValue("scanRejected", true);
+            output.addValue("rejectedEventId", context.get("eventId"));
+            output.addValue("rejectionMessage", rejection.getMessage());
+            output.addValue("scanSaved", false);
+            for(String name : java.util.List.of("acknowledgedEventId", "scanId", "echoScanId", "printJobId", "printStatus", "scanContext"))
+            {
+               output.addValue(name, null);
+            }
+            restorePinnedCopies(run, output);
+            output.getProcessState().setNextStepName("scan");
+         }
          catch(QException failure)
          {
             restorePinnedCopies(run, output);

examples/echo/src/main/java/com/kingsrook/examples/echo/EchoStore.java

@@ -76,9 +76,56 @@ final class EchoStore
                throw new QException("Echo setup is already complete or closed. Leave Echo to choose again.");
             }
             write(connection, "UPDATE echo_run SET state='OPEN',printerRecordId=?,mediaId=?,mediaRevision=?,widthMicrons=?,heightMicrons=?,dpiX=?,dpiY=?,templateId=?,templateRevisionId=?,copies=? WHERE id=?",
-               destination.printerRecordId(), destination.mediaId(), destination.mediaRevision(), Integer.toString(destination.widthMicrons()),
-               Integer.toString(destination.heightMicrons()), Integer.toString(destination.dpiX()), Integer.toString(destination.dpiY()),
-               document.templateId().toString(), document.templateRevisionId().toString(), Integer.toString(copies), id);
+               destination.printerRecordId(), destination.mediaId(), destination.mediaRevision(), destination.widthMicrons(),
+               destination.heightMicrons(), destination.dpiX(), destination.dpiY(),
+               document.templateId(), document.templateRevisionId(), copies, id);
+            connection.commit();
+         }
+         catch(Exception failure)
+         {
+            rollback(connection, failure);
+            if(failure instanceof QException expected)
+            {
+               throw expected;
+            }
+            throw unavailable();
+         }
+      }
+      catch(SQLException failure)
+      {
+         throw unavailable();
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Canonical capture already retains invalid barcode evidence. A pre-admission
+    ** refusal is safe only for an owned open run with no uncertain or prior work.
+    ***************************************************************************/
+   void requireUnadmitted(String runId, MobileDeviceAuthorization.Identity identity, String scanId, Integer copies) throws QException
+   {
+      try(Connection connection = dataSource.getConnection())
+      {
+         connection.setAutoCommit(false);
+         try
+         {
+            Run run = run(connection, runId, identity);
+            if(!"OPEN".equals(run.state()) || run.pending() != null || copies != null && copies != run.copies())
+            {
+               throw new QException("This run cannot acknowledge a new rejected scan; resolve its current state first.");
+            }
+            try(PreparedStatement query = connection.prepareStatement("SELECT id FROM echo_scan WHERE id=?"))
+            {
+               query.setString(1, scanId);
+               try(ResultSet rows = query.executeQuery())
+               {
+                  if(rows.next())
+                  {
+                     throw new QException("This scan has prior work and requires reconciliation.");
+                  }
+               }
+            }
             connection.commit();
          }
          catch(Exception failure)
@@ -167,6 +214,10 @@ final class EchoStore
                connection.commit();
                return new Admission(id, destination, acceptedJob, false, pinned, run.document(), run.copies());
             }
+            if("REJECTED".equals(state) && pinned == null)
+            {
+               throw new EchoScanRejected("This barcode was rejected before printing. Scan a barcode matching the selected document.");
+            }
             if(run.pending() != null && !run.pending().equals(scan.eventId()))
             {
                throw new QException("The previous print is unconfirmed. Retry that scan or leave Echo before starting another.");
@@ -220,11 +271,11 @@ final class EchoStore
       try(Connection connection = dataSource.getConnection(); PreparedStatement statement = connection.prepareStatement(
          "UPDATE echo_scan SET state='IN_FLIGHT',templateId=?,templateRevisionId=?,format=?,topMicrons=?,rightMicrons=?,bottomMicrons=?,leftMicrons=? WHERE id=? AND state IN ('IN_FLIGHT','ATTENTION') AND templateId IS NULL"))
       {
-         String[] values = {plan.templateId().toString(), plan.templateRevisionId().toString(), plan.format().name(), plan.stock().topMicrons().toString(),
-            plan.stock().rightMicrons().toString(), plan.stock().bottomMicrons().toString(), plan.stock().leftMicrons().toString(), scanId};
+         Object[] values = {plan.templateId(), plan.templateRevisionId(), plan.format().name(), plan.stock().topMicrons(),
+            plan.stock().rightMicrons(), plan.stock().bottomMicrons(), plan.stock().leftMicrons(), scanId};
          for(int index = 0; index < values.length; index++)
          {
-            statement.setString(index + 1, values[index]);
+            statement.setObject(index + 1, values[index]);
          }
          if(statement.executeUpdate() != 1)
          {
@@ -268,6 +319,43 @@ final class EchoStore
 
 
 
+   /***************************************************************************
+    ** The pin and rejection compare-and-set compete; only one can win. Preserve
+    ** the rejected capture, and release only its exact pending run binding.
+    ***************************************************************************/
+   void reject(String runId, String scanId, String eventId) throws QException
+   {
+      try(Connection connection = dataSource.getConnection())
+      {
+         connection.setAutoCommit(false);
+         try(PreparedStatement statement = connection.prepareStatement(
+            "UPDATE echo_scan SET state='REJECTED' WHERE id=? AND runId=? AND eventId=? AND state IN ('IN_FLIGHT','ATTENTION') AND templateId IS NULL AND templateRevisionId IS NULL AND printJobId IS NULL"))
+         {
+            statement.setString(1, scanId);
+            statement.setString(2, runId);
+            statement.setString(3, eventId);
+            if(statement.executeUpdate() != 1)
+            {
+               connection.rollback();
+               throw new QException("This scan requires reconciliation; it cannot be acknowledged as rejected.");
+            }
+            write(connection, "UPDATE echo_run SET pendingEventId=NULL WHERE id=? AND pendingEventId=?", runId, eventId);
+            connection.commit();
+         }
+         catch(SQLException failure)
+         {
+            rollback(connection, failure);
+            throw unavailable();
+         }
+      }
+      catch(SQLException failure)
+      {
+         throw unavailable();
+      }
+   }
+
+
+
    /***************************************************************************
     ** A failed or lost response keeps its event identity and pending run binding.
     ** No automatic retry, replacement print request or success acknowledgment.
@@ -378,13 +466,13 @@ final class EchoStore
    /***************************************************************************
     ** All SQL identifiers are fixed source; external values are bound parameters.
     ***************************************************************************/
-   private static void write(Connection connection, String sql, String... values) throws SQLException
+   private static void write(Connection connection, String sql, Object... values) throws SQLException
    {
       try(PreparedStatement statement = connection.prepareStatement(sql))
       {
          for(int index = 0; index < values.length; index++)
          {
-            statement.setString(index + 1, values[index]);
+            statement.setObject(index + 1, values[index]);
          }
          statement.executeUpdate();
       }

examples/echo/src/main/resources/db/echo-postgres.sql

@@ -0,0 +1,29 @@
+-- Copyright (c) 2026 Kingsrook, LLC. SPDX-License-Identifier: Apache-2.0
+-- Host migration input, not automatically executed by metadata registration.
+CREATE TABLE IF NOT EXISTS echo_run (
+   id VARCHAR(36) PRIMARY KEY, actorId VARCHAR(200) NOT NULL, deviceId VARCHAR(36) NOT NULL,
+   publicSessionId VARCHAR(36) NOT NULL, printerRecordId VARCHAR(200) NOT NULL, mediaId VARCHAR(200) NOT NULL,
+   mediaRevision VARCHAR(64) NOT NULL DEFAULT '', widthMicrons INT NOT NULL DEFAULT 0, heightMicrons INT NOT NULL DEFAULT 0,
+   dpiX INT NOT NULL DEFAULT 0, dpiY INT NOT NULL DEFAULT 0,
+   state VARCHAR(30) NOT NULL, pendingEventId VARCHAR(36)
+);
+-- Preserving migration: the document chosen once at setup. Existing rows keep NULL and are never cleared.
+ALTER TABLE echo_run ADD COLUMN IF NOT EXISTS templateId INT;
+ALTER TABLE echo_run ADD COLUMN IF NOT EXISTS templateRevisionId INT;
+CREATE TABLE IF NOT EXISTS echo_scan (
+   id VARCHAR(64) PRIMARY KEY, runId VARCHAR(36) NOT NULL REFERENCES echo_run(id),
+   eventId VARCHAR(36) NOT NULL, actorId VARCHAR(200) NOT NULL, deviceId VARCHAR(36) NOT NULL, mobileScanId VARCHAR(64) NOT NULL,
+   barcode VARCHAR(4096) NOT NULL, symbology VARCHAR(200) NOT NULL, rendererSymbology VARCHAR(100) NOT NULL,
+   scanSource VARCHAR(200) NOT NULL, capturedAt VARCHAR(40) NOT NULL, receivedAt VARCHAR(40) NOT NULL, state VARCHAR(30) NOT NULL,
+   printJobId VARCHAR(200), UNIQUE(runId, eventId)
+   ,templateId INT, templateRevisionId INT, format VARCHAR(10), topMicrons INT, rightMicrons INT, bottomMicrons INT, leftMicrons INT
+);
+-- Preserving migration: the scanner's AIM identifier (for example ]E0), when the capture carried one. Existing rows keep NULL
+-- (no AIM was recorded) and are never rewritten. Other databases need the equivalent additive nullable VARCHAR(3) column.
+ALTER TABLE echo_scan ADD COLUMN IF NOT EXISTS aimIdentifier VARCHAR(3);
+-- Preserving migration: copies printed per scan, chosen once at setup. Existing runs keep exactly one copy (their prior behaviour).
+-- Other databases need the equivalent additive INT NOT NULL DEFAULT 1 column.
+ALTER TABLE echo_run ADD COLUMN IF NOT EXISTS copies INT NOT NULL DEFAULT 1;
+-- Derived canonical GS1 input and HRI. Original barcode is never rewritten. Other hosts need equivalent nullable columns.
+ALTER TABLE echo_scan ADD COLUMN IF NOT EXISTS rendererValue VARCHAR(4096);
+ALTER TABLE echo_scan ADD COLUMN IF NOT EXISTS humanReadable VARCHAR(4096);

examples/echo/src/test/java/com/kingsrook/examples/echo/EchoAppVisibilityTest.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2026 Kingsrook, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package com.kingsrook.examples.echo;
+
+
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput;
+import com.kingsrook.qqq.backend.core.model.actions.metadata.ProcessMetaDataInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.model.session.QUser;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+
+/** Navigation does not perform scanning; execution retains approved-device checks. */
+class EchoAppVisibilityTest
+{
+   /** Remove the synthetic session after each test. */
+   @AfterEach
+   void clear()
+   {
+      QContext.clear();
+   }
+
+   /** Authorized navigation must not require hardware enrollment. */
+   @Test
+   void authorizedBrowserCanSeeAppWithoutADevice()
+   {
+      QContext.init(null, new QSession().withUser(new QUser().withIdReference("fake-operator")).withPermissions("echo.use"));
+      assertDoesNotThrow(() -> new EchoPermissions().checkPermissionsThrowing(new AbstractActionInput(), new QAppMetaData().withName("echo")));
+   }
+
+   /** Navigation remains permission protected. */
+   @Test
+   void browserWithoutEchoPermissionCannotSeeApp()
+   {
+      QContext.init(null, new QSession().withUser(new QUser().withIdReference("fake-operator")));
+      assertThrows(QPermissionDeniedException.class,
+         () -> new EchoPermissions().checkPermissionsThrowing(new AbstractActionInput(), new QAppMetaData().withName("echo")));
+   }
+
+   /** Seeing the app never authorizes scanning without an approved device. */
+   @Test
+   void browserWithoutApprovedDeviceCannotExecuteScanProcess()
+   {
+      QContext.init(null, new QSession().withUser(new QUser().withIdReference("fake-operator")).withPermissions("echo.use"));
+      assertThrows(QPermissionDeniedException.class,
+         () -> new EchoPermissions().checkPermissionsThrowing(new RunProcessInput(), new QProcessMetaData().withName("echoPrint")));
+   }
+
+   /** Catalog discovery exposes the process without performing its device-bound setup. */
+   @Test
+   void authorizedBrowserCanDiscoverProcessWithoutADevice()
+   {
+      QContext.init(null, new QSession().withUser(new QUser().withIdReference("fake-operator")).withPermissions("echo.use"));
+      assertDoesNotThrow(() -> new EchoPermissions().checkPermissionsThrowing(new MetaDataInput(), new QProcessMetaData().withName("echoPrint")));
+      assertDoesNotThrow(
+         () -> new EchoPermissions().checkPermissionsThrowing(new ProcessMetaDataInput(), new QProcessMetaData().withName("echoPrint")));
+   }
+
+   /** Catalog discovery still requires Echo permission. */
+   @Test
+   void browserWithoutPermissionCannotDiscoverProcess()
+   {
+      QContext.init(null, new QSession().withUser(new QUser().withIdReference("fake-operator")));
+      assertThrows(QPermissionDeniedException.class,
+         () -> new EchoPermissions().checkPermissionsThrowing(new MetaDataInput(), new QProcessMetaData().withName("echoPrint")));
+   }
+}
+

examples/echo/src/test/java/com/kingsrook/examples/echo/EchoCenteredLabelTest.java

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2026 Kingsrook, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package com.kingsrook.examples.echo;
+
+
+import org.json.JSONObject;
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+
+/*******************************************************************************
+ ** Published centered GS1 scenes retain the same data and placement contract.
+ *******************************************************************************/
+class EchoCenteredLabelTest
+{
+   static final String SCENE = """
+      {"schema":"qqq-zpl-scene/1","elements":[
+        {"type":"barcode","symbology":"gs1-128","valuePath":"/record/rendererValue","quiet":10,"x":36,"y":36,
+         "fit":{"widthMicrons":95504,"heightMicrons":16000},"align":"center"},
+        {"type":"rasterText","valuePath":"/record/humanReadable","x":36,"y":206,"fontAsset":"forge-echo-abel-regular",
+         "fontSize":44,"width":1128,"height":58,"align":"center"}]}
+      """;
+
+
+
+   /** Both renderer-supported human-readable element forms are admitted. */
+   @Test
+   void centeredRasterAndLegacyTextAreBothGs1Documents()
+   {
+      assertEquals(EchoPrintingDestinations.SceneMode.GS1, EchoPrintingDestinations.sceneMode(SCENE));
+      assertEquals(EchoPrintingDestinations.SceneMode.GS1, EchoPrintingDestinations.sceneMode(SCENE.replace("rasterText", "text")));
+   }
+
+
+
+   /** Text remains derived from GS1 data and below the barcode origin. */
+   @Test
+   void wrongHumanReadableBindingOrPlacementStillRefuses()
+   {
+      for(String type : java.util.List.of("text", "rasterText"))
+      {
+         JSONObject wrong = new JSONObject(SCENE.replace("rasterText", type));
+         wrong.getJSONArray("elements").getJSONObject(1).put("valuePath", "/record/barcode");
+         assertNull(EchoPrintingDestinations.sceneMode(wrong.toString()));
+         for(int y : java.util.List.of(35, 36))
+         {
+            JSONObject above = new JSONObject(SCENE.replace("rasterText", type));
+            above.getJSONArray("elements").getJSONObject(1).put("y", y);
+            assertNull(EchoPrintingDestinations.sceneMode(above.toString()));
+         }
+      }
+   }
+
+
+
+   /** Raster text never relaxes the barcode binding or bounded fit requirement. */
+   @Test
+   void barcodeBindingAndFitRemainMandatory()
+   {
+      assertNull(EchoPrintingDestinations.sceneMode(SCENE.replace("/record/rendererValue", "/record/barcode")));
+      JSONObject scene = new JSONObject(SCENE);
+      scene.getJSONArray("elements").getJSONObject(0).remove("fit");
+      assertNull(EchoPrintingDestinations.sceneMode(scene.toString()));
+   }
+
+
+
+   /** Human-readable stock dimensions preserve native profile identities. */
+   @Test
+   void readableStockNamesPreserveIdentityAndBothResolutions() throws Exception
+   {
+      assertEquals("4 × 1 in label · 300 dpi", label("4 x 1", 101600, 25400, 300, 300));
+      assertEquals("4 × 1 in label · 300 dpi", label("Windows queue default (101.6 × 25.4 mm, 300 × 300 DPI)", 101600, 25400, 300, 300));
+      assertEquals("100 × 50 mm label · 203 dpi", label("100 x 50 mm", 100000, 50000, 203, 203));
+      assertEquals("Shipping · 4 × 1 in label · 300 × 600 dpi", label("Shipping", 101600, 25400, 300, 600));
+   }
+
+
+
+   /** Build one synthetic printer profile using the existing owner wire schema. */
+   private static String label(String name, int width, int height, int dpiX, int dpiY) throws Exception
+   {
+      JSONObject profile = new JSONObject().put("id", "synthetic-media").put("revision", "a".repeat(64)).put("name", name)
+         .put("widthMicrons", width).put("heightMicrons", height).put("dpiX", dpiX).put("dpiY", dpiY)
+         .put("source", "WINDOWS_QUEUE_DEFAULT").put("applyMode", "DRIVER_DEFAULT");
+      var choice = EchoPrintingDestinations.choices(new org.json.JSONArray().put(profile).toString()).getFirst();
+      assertEquals("synthetic-media", choice.id());
+      return choice.label();
+   }
+}

examples/echo/src/test/java/com/kingsrook/examples/echo/EchoOwnerAdaptersTest.java

@@ -191,9 +191,9 @@ class EchoOwnerAdaptersTest
       List<EchoDestinations.MediaChoice> choices = EchoPrintingDestinations.choices(PROFILES);
       assertEquals(1, choices.size());
       assertEquals("4x6", choices.getFirst().id());
-      assertTrue(choices.getFirst().label().contains("101.6 x 152.4 mm, 300 dpi"));
-      assertEquals(1, EchoMediaChoices.select(choices, null, "4 x", 0, 50).size());
-      assertEquals(0, EchoMediaChoices.select(choices, null, "label", 0, 50).size());
+      assertEquals("4 × 6 in label · 300 dpi", choices.getFirst().label());
+      assertEquals(1, EchoMediaChoices.select(choices, null, "4 ×", 0, 50).size());
+      assertEquals(1, EchoMediaChoices.select(choices, null, "label", 0, 50).size());
       assertEquals(0, EchoMediaChoices.select(choices, List.of("2x1"), null, 0, 50).size());
       assertEquals("4x6", EchoMediaChoices.select(choices, List.of("4x6"), null, 0, 50).getFirst().getId());
       assertEquals(0, EchoMediaChoices.select(choices, null, null, 1, 50).size());

examples/echo/src/test/java/com/kingsrook/examples/echo/EchoPostgresTest.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2026 Kingsrook, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package com.kingsrook.examples.echo;
+
+
+import java.nio.charset.StandardCharsets;
+import java.util.UUID;
+import com.kingsrook.qbits.documentgeneration.GenerationPorts;
+import com.kingsrook.qbits.mobilescanners.EchoMobileFixture;
+import com.kingsrook.qbits.mobilescanners.MobileDeviceAuthorization;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
+import org.postgresql.ds.PGSimpleDataSource;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+
+/*******************************************************************************
+ ** Isolated PostgreSQL 17 contract: numeric bindings, preserving DDL and pin CAS.
+ *******************************************************************************/
+class EchoPostgresTest
+{
+   /***************************************************************************
+    ** No production database credentials are used; the caller supplies a fixture.
+    ***************************************************************************/
+   @Test
+   @EnabledIfSystemProperty(named = "echo.postgres.url", matches = ".+")
+   void setupAndPinUseNativeIntegerBindings() throws Exception
+   {
+      PGSimpleDataSource dataSource = new PGSimpleDataSource();
+      dataSource.setURL(System.getProperty("echo.postgres.url"));
+      dataSource.setUser("postgres");
+      String schema = "echo_fixture_" + UUID.randomUUID().toString().replace("-", "");
+      try(var connection = dataSource.getConnection(); var statement = connection.createStatement())
+      {
+         assertEquals(17, connection.getMetaData().getDatabaseMajorVersion());
+         statement.execute("CREATE SCHEMA " + schema);
+      }
+      dataSource.setCurrentSchema(schema);
+      try
+      {
+         String sql;
+         try(var resource = getClass().getResourceAsStream("/db/echo-postgres.sql"))
+         {
+            sql = new String(resource.readAllBytes(), StandardCharsets.UTF_8);
+         }
+         try(var connection = dataSource.getConnection(); var statement = connection.createStatement())
+         {
+            statement.execute(sql);
+         }
+         new EchoMobileFixture(new QInstance(), "jdbc:h2:mem:" + schema + ";DATABASE_TO_UPPER=FALSE;DB_CLOSE_DELAY=-1");
+         var identity = MobileDeviceAuthorization.captureCurrent().orElseThrow();
+         EchoStore store = new EchoStore(dataSource);
+         store.begin("synthetic-run", identity);
+         var destination = new EchoDestinations.Destination("synthetic-printer", "4x6", "synthetic-revision", 101600, 152400, 300, 300);
+         store.select("synthetic-run", identity, destination, new EchoDestinations.Document(7, 11), 3);
+         assertEquals(3, store.copies("synthetic-run", identity));
+         try(var connection = dataSource.getConnection(); var statement = connection.createStatement())
+         {
+            statement.execute("INSERT INTO echo_scan(id,runId,eventId,actorId,deviceId,mobileScanId,barcode,symbology,rendererSymbology,scanSource,capturedAt,receivedAt,state)"
+               + " VALUES ('synthetic-scan','synthetic-run','synthetic-event','synthetic-actor','synthetic-device','synthetic-mobile-scan','001234','CODE128','code128','fixture','fixture','fixture','IN_FLIGHT')");
+         }
+         var plan = new EchoDestinations.Plan(7, 11, new GenerationPorts.Stock(101600, 152400, 3000, 3000, 3000, 3000, 300), GenerationPorts.Format.ZPL);
+         store.requireUnadmitted("synthetic-run", identity, "new-scan", 3);
+         assertThrows(QException.class, () -> store.requireUnadmitted("synthetic-run", identity, "synthetic-scan", 3));
+         store.pin("synthetic-scan", plan);
+         assertThrows(EchoStore.PinNotWon.class, () -> store.pin("synthetic-scan", plan));
+         assertThrows(QException.class, () -> store.reject("synthetic-run", "synthetic-scan", "synthetic-event"));
+         try(var connection = dataSource.getConnection(); var statement = connection.createStatement())
+         {
+            statement.execute("INSERT INTO echo_scan(id,runId,eventId,actorId,deviceId,mobileScanId,barcode,symbology,rendererSymbology,scanSource,capturedAt,receivedAt,state)"
+               + " VALUES ('rejected-scan','synthetic-run','rejected-event','synthetic-actor','synthetic-device','rejected-mobile','synthetic','QRCODE','qr','fixture','fixture','fixture','IN_FLIGHT')");
+            statement.execute("UPDATE echo_run SET pendingEventId='rejected-event' WHERE id='synthetic-run'");
+         }
+         assertThrows(QException.class, () -> store.requireUnadmitted("synthetic-run", identity, "new-scan", 3));
+         store.reject("synthetic-run", "rejected-scan", "rejected-event");
+         assertThrows(EchoStore.PinNotWon.class, () -> store.pin("rejected-scan", plan));
+         store.requireUnadmitted("synthetic-run", identity, "new-scan", 3);
+
+         try(var connection = dataSource.getConnection(); var statement = connection.createStatement())
+         {
+            statement.execute(sql);
+            try(var rows = statement.executeQuery("SELECT templateId,templateRevisionId,topMicrons,barcode,rendererValue,humanReadable FROM echo_scan WHERE id='synthetic-scan'"))
+            {
+               assertTrue(rows.next());
+               assertEquals(7, rows.getInt(1));
+               assertEquals(11, rows.getInt(2));
+               assertEquals(3000, rows.getInt(3));
+               assertEquals("001234", rows.getString(4));
+               assertEquals(null, rows.getString(5));
+               assertEquals(null, rows.getString(6));
+            }
+         }
+      }
+      finally
+      {
+         EchoMobileFixture.clear();
+         try(var connection = dataSource.getConnection(); var statement = connection.createStatement())
+         {
+            statement.execute("DROP SCHEMA " + schema + " CASCADE");
+         }
+      }
+   }
+}

examples/echo/src/test/java/com/kingsrook/examples/echo/EchoTest.java

@@ -67,6 +67,7 @@ class EchoTest
    private Runnable afterAccept;
    private Runnable afterLookup;
    private QInstance metadata;
+   private boolean rejectQr;
    private boolean documentWithdrawn;
    private int documentRevisionShift;
    private final List<Integer> plannedDocuments = new java.util.concurrent.CopyOnWriteArrayList<>();
@@ -156,6 +157,10 @@ class EchoTest
          @Override
          public Plan plan(MobileDeviceAuthorization.Identity identity, Destination destination, Document document, EchoService.Scan scan) throws QException
          {
+            if(rejectQr && "QRCODE".equals(scan.symbology()))
+            {
+               throw new EchoScanRejected("Wrong barcode type; no print was requested.");
+            }
             plannedDocuments.add(document.templateId());
             if(!authorizeDocument(identity, destination, document.templateId()).equals(document))
             {
@@ -273,6 +278,21 @@ class EchoTest
     ** Setup is a real frontend, then both scans return to the same scan step.
     ***************************************************************************/
    @Test
+   void echoPrintingUsesProcessIdentityAndIcon()
+   {
+      var process = QContext.getQInstance().getProcess(EchoQBitProducer.PROCESS);
+      assertEquals("echoPrint", process.getName());
+      assertEquals("Echo Printing", process.getLabel());
+      assertEquals("account_tree", process.getIcon().getName());
+      assertEquals("Echo Scans", QContext.getQInstance().getTable(EchoQBitProducer.SCAN_TABLE).getLabel());
+   }
+
+
+
+   /*******************************************************************************
+    ** Existing runtime behavior remains unchanged by presentation metadata.
+    *******************************************************************************/
+   @Test
    void processChoosesOnceAndLoopsWithExactSymbology() throws Exception
    {
       RunProcessOutput setup = new RunProcessAction().execute(new RunProcessInput().withInputSource(com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource.USER).withProcessName(EchoQBitProducer.PROCESS));
@@ -310,6 +330,93 @@ class EchoTest
 
 
 
+   /***************************************************************************
+    ** Rejection releases scanning without losing setup or retaining receipts.
+    ***************************************************************************/
+   @Test
+   void rejectedBarcodeKeepsSetupAndClearsReceipts() throws Exception
+   {
+      rejectQr = true;
+      RunProcessOutput setup = new RunProcessAction().execute(new RunProcessInput().withInputSource(com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource.USER).withProcessName(EchoQBitProducer.PROCESS));
+      RunProcessOutput ready = new RunProcessAction().execute(resume(setup, "setup").withValue("printerId", "printer").withValue("mediaId", "4x6").withValue("templateId", 7).withValue("copies", 3));
+      for(int index = 0; index < 2; index++)
+      {
+         RunProcessInput wrong = resume(ready, "scan");
+         wrong.getValues().putAll(event("QRCODE", "synthetic-wrong-type"));
+         String rejectedEvent = wrong.getValueString("eventId");
+         RunProcessOutput rejected = new RunProcessAction().execute(wrong);
+         assertEquals(true, rejected.getValue("scanRejected"));
+         assertEquals(rejectedEvent, rejected.getValue("rejectedEventId"));
+         assertEquals(false, rejected.getValue("scanSaved"));
+         assertNull(rejected.getValue("acknowledgedEventId"));
+         assertNull(rejected.getValue("scanId"));
+         assertNull(rejected.getValue("printJobId"));
+         assertEquals(index, requests.size());
+         for(String field : List.of("echoRunId", "printerId", "mediaId", "templateId", "copies"))
+         {
+            assertEquals(ready.getValue(field), rejected.getValue(field));
+         }
+         ready = scan(rejected, "CODE128", "synthetic-valid");
+         assertEquals(true, ready.getValue("scanSaved"));
+         assertEquals(false, ready.getValue("scanRejected"));
+         assertNull(ready.getValue("rejectedEventId"));
+         assertNull(ready.getValue("rejectionMessage"));
+         assertEquals(index + 1, requests.size());
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** Rejected replays never print; a won pin cannot be relabeled as rejection.
+    ***************************************************************************/
+   @Test
+   void rejectionCannotReleasePinnedWorkAndReplayRemainsRejected() throws Exception
+   {
+      rejectQr = true;
+      String run = config.service.start("printer", "4x6", 7, 3);
+      var wrong = captured("QRCODE", "synthetic-wrong-type");
+      assertThrows(EchoScanRejected.class, () -> config.service.print(run, wrong));
+      assertThrows(EchoScanRejected.class, () -> config.service.print(run, wrong));
+      assertTrue(requests.isEmpty());
+      var valid = captured("CODE128", "synthetic-valid");
+      var receipt = config.service.print(run, valid);
+      var store = new EchoStore(dataSource);
+      assertThrows(QException.class, () -> store.reject(run, receipt.scanId(), receipt.eventId()));
+      assertEquals(receipt, config.service.print(run, valid));
+      assertEquals(1, requests.size());
+      assertThrows(QException.class, () -> store.pin(wrong.get("scanId").toString(), acceptedPlans.get("echo:" + receipt.scanId())));
+   }
+
+
+
+   /***************************************************************************
+    ** Unsupported types and invalid GS1 return ready without losing setup.
+    ***************************************************************************/
+   @Test
+   void unsupportedAndInvalidGs1RecoverButUncertainWorkDoesNot() throws Exception
+   {
+      RunProcessOutput setup = new RunProcessAction().execute(new RunProcessInput().withInputSource(com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource.USER).withProcessName(EchoQBitProducer.PROCESS));
+      RunProcessOutput ready = new RunProcessAction().execute(resume(setup, "setup").withValue("printerId", "printer").withValue("mediaId", "4x6").withValue("templateId", 7));
+      RunProcessOutput unsupported = scan(ready, "MAXICODE", "synthetic");
+      assertEquals(true, unsupported.getValue("scanRejected"));
+      RunProcessInput invalid = resume(unsupported, "scan");
+      invalid.getValues().putAll(event("CODE128", "invalid-gs1"));
+      invalid.addValue("aimIdentifier", "]C1");
+      invalid.addValue("rawDataBase64", java.util.Base64.getEncoder().encodeToString("invalid-gs1".getBytes(StandardCharsets.US_ASCII)));
+      RunProcessOutput rejected = new RunProcessAction().execute(invalid);
+      assertEquals(true, rejected.getValue("scanRejected"));
+      assertTrue(requests.isEmpty());
+      assertEquals(true, scan(rejected, "CODE128", "synthetic-valid").getValue("scanSaved"));
+      String run = ready.getValueString("echoRunId");
+      uncertain = true;
+      assertThrows(QException.class, () -> config.service.print(run, captured("CODE128", "uncertain")));
+      QException blocked = assertThrows(QException.class, () -> config.service.print(run, captured("MAXICODE", "unsupported")));
+      assertFalse(blocked instanceof EchoScanRejected);
+   }
+
+
+
    /***************************************************************************
     ** Runs without a chosen count print exactly one copy, and the run stores it.
     ***************************************************************************/
@@ -1481,6 +1588,13 @@ class EchoTest
       config.service.close(run);
       desktop("operator", true);
       assertEquals("000001", source(acceptedScan.scanId()).getValueString("barcode"));
+      var metadataInput = new com.kingsrook.qqq.backend.core.model.actions.metadata.ProcessMetaDataInput();
+      metadataInput.setProcessName(EchoQBitProducer.PROCESS);
+      var processView = new com.kingsrook.qqq.backend.core.actions.metadata.ProcessMetaDataAction().execute(metadataInput);
+      assertTrue(processView.getProcess().getHasPermission());
+      assertThrows(QException.class, () -> new RunProcessAction().execute(new RunProcessInput()
+         .withInputSource(com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource.USER).withProcessName(EchoQBitProducer.PROCESS)));
+      assertThrows(QException.class, () -> config.service.begin(UUID.randomUUID().toString()));
       assertThrows(QException.class, () -> config.service.print(run, context));
       assertThrows(QException.class, () -> new EchoPermissions().checkPermissionsThrowing(
          new RunProcessInput().withProcessName(EchoQBitProducer.PROCESS), QContext.getQInstance().getProcess(EchoQBitProducer.PROCESS)));
@@ -1617,3 +1731,5 @@ class EchoTest
          "eventId", UUID.randomUUID().toString(), "capturedAt", "2026-11-01T17:00:00Z"));
    }
 }
+
+

examples/echo/src/test/java/com/kingsrook/examples/echo/fixture/EchoHttpFixtureTest.java

@@ -66,7 +66,7 @@ class EchoHttpFixtureTest
             JSONObject item = (JSONObject) extension;
             if("mobile-scanners".equals(item.getString("name")))
             {
-               mobile15 = "1.5.0".equals(item.getString("version"));
+               mobile15 = item.getString("version").matches("1\\.([5-9]|[1-9][0-9]+)\\.[0-9]+");
             }
          }
          assertTrue(mobile15);
@@ -111,7 +111,23 @@ class EchoHttpFixtureTest
          assertTrue(firstValues.getString("printJobId").startsWith("fixture-job-"));
          JSONObject retry = complete(form("/qqq/v1/processes/echoPrint/" + process + "/step/scan", scanner, firstEvent, true), EchoQBitProducer.PROCESS, scanner, true);
          assertEquals(firstValues.getString("printJobId"), retry.getJSONObject("values").getString("printJobId"));
+         JSONObject unsupported = event("MAXICODE");
+         JSONObject rejected = complete(form("/qqq/v1/processes/echoPrint/" + process + "/step/scan", scanner, unsupported, true), EchoQBitProducer.PROCESS, scanner, true);
+         assertEquals("scan", rejected.getString("nextStep"));
+         JSONObject rejection = rejected.getJSONObject("values");
+         assertTrue(rejection.getBoolean("scanRejected"));
+         assertFalse(rejection.getBoolean("scanSaved"));
+         assertEquals(unsupported.getString("eventId"), rejection.getString("rejectedEventId"));
+         assertFalse(rejection.getString("rejectionMessage").isBlank());
+         assertEquals(run, rejection.getString("echoRunId"));
+         for(String cleared : java.util.List.of("acknowledgedEventId", "scanId", "printJobId"))
+         {
+            assertTrue(rejection.isNull(cleared), "No prior positive receipt survives rejection.");
+         }
          JSONObject second = complete(form("/qqq/v1/processes/echoPrint/" + process + "/step/scan", scanner, event("QRCODE"), true), EchoQBitProducer.PROCESS, scanner, true);
+         assertFalse(second.getJSONObject("values").getBoolean("scanRejected"));
+         assertTrue(second.getJSONObject("values").isNull("rejectedEventId"));
+         assertTrue(second.getJSONObject("values").isNull("rejectionMessage"));
          assertEquals(run, second.getJSONObject("values").getString("echoRunId"));
          assertEquals("scan", second.getString("nextStep"));
          JSONArray scans = query(EchoQBitProducer.SCAN_TABLE, scanner);

integrations/record-files/IsolatedBuildPaths.ps1

@@ -58,8 +58,13 @@ function Initialize-IsolatedScannerSource
    Remove-IsolatedBuildDirectory -ModuleRoot $ModuleRoot -LeafName 'scanner-source'
    $destination = Join-Path $ModuleRoot 'target/scanner-source'
    New-Item -ItemType Directory -Path $destination -Force | Out-Null
-   foreach($name in @('pom.xml', 'mvnw.cmd', 'mvnw', '.mvn', 'src', 'checkstyle'))
+   foreach($name in @('mvnw.cmd', 'mvnw', '.mvn', 'checkstyle'))
    {
       Copy-Item -LiteralPath (Join-Path $ScannerRoot $name) -Destination $destination -Recurse -Force
    }
+   # The scanner base module (pom.xml, src) lives in base/ since the reactor layout; the scratch tree keeps the single-module shape.
+   foreach($name in @('pom.xml', 'src'))
+   {
+      Copy-Item -LiteralPath (Join-Path (Join-Path $ScannerRoot 'base') $name) -Destination $destination -Recurse -Force
+   }
 }

integrations/record-files/README.md

@@ -70,16 +70,23 @@ OpenAPI identifiers are `getQbitRecordFilesCapabilities`,
 `postQbitRecordFilesUploadsByUploadIdCancel`. Native invoker/credential-scope IDs
 instead use `METHOD /qbit/record-files/...`; capability gating must distinguish them.
 
-## Publication preparation
+## Publication
 
-This module is a standard QBit module (parent `qbit-build-parent` 2.1.0, Apache-2.0
-metadata, canonical Gitea URLs) and produces a separate JAR from the root
-scanner; the root has no module or dependency on it. Preparing the POM is not
-publication. Publishing still requires a full immutable (non-SNAPSHOT) dependency set
-and the normal hosted qualification and publication path. No public version of this
-module exists, and no release test is claimed here.
+This module is a module of the repository's reactor (root `pom.xml`, artifact
+`qbit-mobile-scanners-reactor`), next to `base` (`qbit-mobile-scanners`). It inherits
+the root's single `<revision>` and the same `qbit-build-parent` 2.1.0, Apache-2.0
+metadata and canonical Gitea URLs. One root `mvn deploy` (the shared Gitea Actions
+`maven` workflow) tests and publishes the reactor POM, `qbit-mobile-scanners` and
+`qbit-mobile-scanners-record-files` at one version to the Gitea Maven registry.
+Its dependencies are immutable releases from that registry: `qbit-record-files`
+0.1.0-RC.1 and `qbit-collaboration` 1.1.0-RC.1, with QQQ 4.1.0-RC.22 from the root.
+Build only this module and the base with `./mvnw -pl integrations/record-files -am verify`.
 
-## Reproducible isolated verification
+## Reproducible isolated verification (legacy local harness)
+
+The isolated scripts below date from the pre-publication frozen-candidate adoption on a
+Windows workstation and are not part of the release path; they predate the reactor
+layout and are kept as evidence tooling only.
 
 From this directory, run `./Verify-Isolated.ps1`. It verifies every checksum in the
 retained bundle, seeds a private repository from the local Maven cache, copies and

integrations/record-files/Test-IsolatedBuildPaths.ps1

@@ -8,12 +8,12 @@ $ErrorActionPreference = 'Stop'
 $test = Join-Path $PSScriptRoot ('target/path-regression-' + [Guid]::NewGuid().ToString('N'))
 $inputRoot = Join-Path $test 'input'
 $moduleRoot = Join-Path $test 'module-root'
-New-Item -ItemType Directory -Force -Path $inputRoot, $moduleRoot, (Join-Path $inputRoot '.mvn'), (Join-Path $inputRoot 'src'), (Join-Path $inputRoot 'checkstyle'), (Join-Path $moduleRoot 'target/isolated-m2') | Out-Null
-foreach($name in @('pom.xml', 'mvnw.cmd', 'mvnw')) { Set-Content -LiteralPath (Join-Path $inputRoot $name) -Value 'fixture' }
-$removedSource = Join-Path $inputRoot 'src/Removed.java'
+New-Item -ItemType Directory -Force -Path $inputRoot, $moduleRoot, (Join-Path $inputRoot '.mvn'), (Join-Path $inputRoot 'base/src'), (Join-Path $inputRoot 'checkstyle'), (Join-Path $moduleRoot 'target/isolated-m2') | Out-Null
+foreach($name in @('mvnw.cmd', 'mvnw', 'base/pom.xml')) { Set-Content -LiteralPath (Join-Path $inputRoot $name) -Value 'fixture' }
+$removedSource = Join-Path $inputRoot 'base/src/Removed.java'
 Set-Content -LiteralPath $removedSource -Value 'old-source'
-New-Item -ItemType Directory -Force -Path (Join-Path $inputRoot 'src/main/resources') | Out-Null
-$removedResource = Join-Path $inputRoot 'src/main/resources/removed.txt'
+New-Item -ItemType Directory -Force -Path (Join-Path $inputRoot 'base/src/main/resources') | Out-Null
+$removedResource = Join-Path $inputRoot 'base/src/main/resources/removed.txt'
 Set-Content -LiteralPath $removedResource -Value 'old-resource'
 $sentinel = Join-Path $moduleRoot 'target/isolated-m2/keep.txt'
 Set-Content -LiteralPath $sentinel -Value 'repository-must-survive'
@@ -23,7 +23,7 @@ New-Item -ItemType Directory -Force -Path (Join-Path $scratch 'target/classes')
 Set-Content -LiteralPath (Join-Path $scratch 'target/classes/Removed.class') -Value 'stale-class'
 Remove-Item -LiteralPath $removedSource
 Remove-Item -LiteralPath $removedResource
-Set-Content -LiteralPath (Join-Path $inputRoot 'src/Current.java') -Value 'current-source'
+Set-Content -LiteralPath (Join-Path $inputRoot 'base/src/Current.java') -Value 'current-source'
 Initialize-IsolatedScannerSource -ScannerRoot $inputRoot -ModuleRoot $moduleRoot
 if((Test-Path -LiteralPath (Join-Path $scratch 'src/Removed.java')) -or (Test-Path -LiteralPath (Join-Path $scratch 'target/classes/Removed.class'))) { throw 'Removed source/class survived the fresh snapshot.' }
 if(Test-Path -LiteralPath (Join-Path $scratch 'src/main/resources/removed.txt')) { throw 'Removed resource survived the fresh snapshot.' }

integrations/record-files/Verify-Isolated.ps1

@@ -110,7 +110,7 @@ try
    Remove-IsolatedBuildDirectory -ModuleRoot $module -LeafName 'module'
    $runtimeClasspath = Join-Path $target 'runtime-classpath.txt'
    if(Test-Path -LiteralPath $runtimeClasspath) { Remove-Item -LiteralPath $runtimeClasspath }
-   Invoke-Maven @('-B', '-ntp', 'clean', 'verify', 'org.apache.maven.plugins:maven-dependency-plugin:3.8.1:build-classpath', '-Dmdep.includeScope=test', '-Dmdep.outputFile=target/runtime-classpath.txt')
+   Invoke-Maven @('-B', '-ntp', '-Pisolated-module', 'clean', 'verify', 'org.apache.maven.plugins:maven-dependency-plugin:3.8.1:build-classpath', '-Dmdep.includeScope=test', '-Dmdep.outputFile=target/runtime-classpath.txt')
    $runtime = (Get-Content -LiteralPath (Join-Path $target 'runtime-classpath.txt') -Raw).Trim().Split(';')
    $manifest = foreach($path in $runtime) { @{path=$path; sha256=(Get-FileHash -LiteralPath $path -Algorithm SHA256).Hash.ToLowerInvariant() } }
    $manifest | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $target 'runtime-sha256.json') -Encoding utf8

integrations/record-files/pom.xml

@@ -1,12 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <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.1.0</version>
-      <relativePath />
-   </parent>
+   <parent><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-mobile-scanners-reactor</artifactId><version>${revision}</version><relativePath>../../pom.xml</relativePath></parent>
    <groupId>com.kingsrook.qbits</groupId>
    <artifactId>qbit-mobile-scanners-record-files</artifactId>
    <version>${revision}</version>
@@ -33,23 +28,13 @@
       <url>https://git.kof22.com/QRun-IO/qbit-mobile-scanners/issues</url>
    </issueManagement>
    <properties>
-      <!-- effective version 0.1.0-SNAPSHOT; the parent's own revision (2.1.0) is overridden here -->
-      <revision>0.1.0-SNAPSHOT</revision>
-      <maven.compiler.release>21</maven.compiler.release>
-      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-      <!-- the same property names the root POM and the Echo demo use, with their defaults -->
-      <qqq.version>4.1.0-RC.21</qqq.version>
-      <mobile.version>0.1.0-SNAPSHOT</mobile.version>
-      <recordfiles.version>0.1.0-SNAPSHOT</recordfiles.version>
-      <collaboration.version>0.1.0-record-files-SNAPSHOT</collaboration.version>
-      <!-- developer-script override for core and rdbms only; by default it is the single qqq line, never a second one -->
-      <qqq.frozen.version>${qqq.version}</qqq.frozen.version>
+      <!-- the base module is built in the same reactor; the others are published releases from the Gitea registry -->
+      <mobile.version>${project.version}</mobile.version>
+      <recordfiles.version>0.4.0-RC.1</recordfiles.version>
+      <collaboration.version>1.2.0-RC.1</collaboration.version>
    </properties>
    <dependencyManagement><dependencies>
       <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-bom-pom</artifactId><version>${qqq.version}</version><type>pom</type><scope>import</scope></dependency>
-      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-core</artifactId><version>${qqq.frozen.version}</version></dependency>
-      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-rdbms</artifactId><version>${qqq.frozen.version}</version></dependency>
-      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-middleware-javalin</artifactId><version>${qqq.version}</version></dependency>
       <dependency><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-collaboration</artifactId><version>${collaboration.version}</version></dependency>
    </dependencies></dependencyManagement>
    <dependencies>
@@ -62,13 +47,20 @@
       <dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-params</artifactId><scope>test</scope></dependency>
       <dependency><groupId>org.assertj</groupId><artifactId>assertj-core</artifactId><version>3.27.7</version><scope>test</scope></dependency>
    </dependencies>
-   <build><directory>${project.basedir}/target/module</directory><plugins>
+   <build><plugins>
       <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.13.0</version></plugin>
-      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.2</version><configuration><systemPropertyVariables><qqq.logger.logSessionId.disabled>true</qqq.logger.logSessionId.disabled></systemPropertyVariables></configuration></plugin>
+      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.6</version><configuration><systemPropertyVariables><qqq.logger.logSessionId.disabled>true</qqq.logger.logSessionId.disabled></systemPropertyVariables></configuration></plugin>
       <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-checkstyle-plugin</artifactId><version>3.6.0</version>
          <dependencies><dependency><groupId>com.puppycrawl.tools</groupId><artifactId>checkstyle</artifactId><version>14.3.0</version></dependency></dependencies>
-         <configuration><configLocation>../../checkstyle/checkstyle.xml</configLocation><includeTestSourceDirectory>true</includeTestSourceDirectory><failOnViolation>true</failOnViolation><violationSeverity>warning</violationSeverity></configuration>
+         <configuration><configLocation>${maven.multiModuleProjectDirectory}/checkstyle/checkstyle.xml</configLocation><includeTestSourceDirectory>true</includeTestSourceDirectory><failOnViolation>true</failOnViolation><violationSeverity>warning</violationSeverity></configuration>
          <executions><execution><id>style</id><phase>validate</phase><goals><goal>check</goal></goals></execution></executions>
       </plugin>
    </plugins></build>
+   <profiles>
+      <!-- Isolated verification (Verify-Isolated.ps1) keeps its module output out of target/ itself; a normal reactor build and the standard capture use target/. -->
+      <profile>
+         <id>isolated-module</id>
+         <build><directory>${project.basedir}/target/module</directory></build>
+      </profile>
+   </profiles>
 </project>

integrations/record-files/src/test/java/com/kingsrook/qbits/mobilescanners/MobileRecordFilesIntegrationTest.java

@@ -78,6 +78,7 @@ import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.CsvSource;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertThrows;
@@ -408,6 +409,58 @@ public class MobileRecordFilesIntegrationTest extends RecordFilesFixture
 
 
 
+   /***************************************************************************
+    ** A host that sets quarantineCapturedFiles=false (and leaves quarantineNewFiles
+    ** true) makes only an approved device's camera item AVAILABLE. The device is
+    ** the one the real provider verified, an unapproved device is still refused,
+    ** an UPLOAD item stays QUARANTINED, and the permitted preview read returns the
+    ** exact retained bytes only for the AVAILABLE version. Requires the owner
+    ** version that contains withQuarantineCapturedFiles.
+    ***************************************************************************/
+   @Test
+   void approvedDeviceCameraPhotoIsAvailableOnlyWhenHostOptsIn() throws Exception
+   {
+      config.withQuarantineCapturedFiles(false);
+      assertTrue(config.getQuarantineNewFiles(), "the broad default stays quarantined");
+      String scanner = signIn("scanner");
+      String admin = signIn("admin");
+      enrollHttp(scanner);
+      assertEquals(403, send("POST", FILES + "/uploads", scanner, manifest(UUID.randomUUID().toString(), "CAMERA", "photo.jpg", "image/jpeg", CONTENT), true, Map.of()).statusCode(),
+         "an unapproved device cannot start a capture upload even with the host opt-in");
+      approveHttp(admin, "mobileDeviceApprove");
+      byte[] photo = {(byte) 0xFF, (byte) 0xD8, 9, 8, 7};
+      byte[] other = {4, 5, 6};
+      assertEquals("AVAILABLE", finalizeLifecycle(scanner, "CAMERA", "photo.jpg", "image/jpeg", photo));
+      assertEquals("QUARANTINED", finalizeLifecycle(scanner, "UPLOAD", "upload.jpg", "image/jpeg", other));
+      QContext.init(instance, authenticated(scanner));
+      var retained = files.listForRecord("document", "1");
+      assertEquals(2, retained.size());
+      var available = retained.stream().filter(file -> "AVAILABLE".equals(file.lifecycle())).findFirst().orElseThrow();
+      var quarantined = retained.stream().filter(file -> "QUARANTINED".equals(file.lifecycle())).findFirst().orElseThrow();
+      var reader = new com.kingsrook.qbits.recordfiles.api.RetainedContentReader(
+         new com.kingsrook.qbits.collaboration.attachments.AttachmentsService(collaboration, new DiskAttachmentStorage()));
+      var reference = reader.reference(available.id(), "preview-" + available.id());
+      assertArrayEquals(photo, reader.read(reference, 1024).bytes());
+      assertThrows(QException.class, () -> reader.reference(quarantined.id(), "preview-" + quarantined.id()));
+   }
+
+
+
+   /***************************************************************************
+    ** Create, upload one chunk and finalize one item; returns its commit lifecycle.
+    ***************************************************************************/
+   private String finalizeLifecycle(String scanner, String origin, String fileName, String mediaType, byte[] bytes) throws Exception
+   {
+      String request = UUID.randomUUID().toString();
+      String id = ok(send("POST", FILES + "/uploads", scanner, manifest(request, origin, fileName, mediaType, bytes), true, Map.of())).path("uploadId").asText();
+      ok(send("PUT", FILES + "/uploads/" + id + "/items/20000000-0000-0000-0000-000000000001/chunks/0", scanner, bytes, true,
+         Map.of("Content-Type", "application/octet-stream", "X-Chunk-SHA256", UploadManifest.hash(bytes))));
+      return ok(send("POST", FILES + "/uploads/" + id + "/finalize", scanner, null, true, Map.of("Idempotency-Key", request)))
+         .at("/receipt/items/0/lifecycleAtCommit").asText();
+   }
+
+
+
    /***************************************************************************
     ** Different actors, missing device proof and revocation cannot resume intake.
     ***************************************************************************/
@@ -822,10 +875,20 @@ public class MobileRecordFilesIntegrationTest extends RecordFilesFixture
     ** Immutable manifest has no device, user or session identity fields.
     ***************************************************************************/
    private byte[] manifest(String request) throws Exception
+   {
+      return manifest(request, "UPLOAD", "fixture.pdf", "application/pdf", CONTENT);
+   }
+
+
+
+   /***************************************************************************
+    ** The same manifest with a chosen client-declared origin and content.
+    ***************************************************************************/
+   private byte[] manifest(String request, String origin, String fileName, String mediaType, byte[] bytes) throws Exception
    {
       return JSON.writeValueAsBytes(Map.of("requestId", request, "parent", Map.of("tableName", "document", "recordId", "1"),
-         "items", List.of(Map.of("itemId", "20000000-0000-0000-0000-000000000001", "position", 0, "fileName", "fixture.pdf", "declaredMediaType", "application/pdf",
-            "sizeBytes", CONTENT.length, "sha256", UploadManifest.hash(CONTENT), "origin", "UPLOAD"))));
+         "items", List.of(Map.of("itemId", "20000000-0000-0000-0000-000000000001", "position", 0, "fileName", fileName, "declaredMediaType", mediaType,
+            "sizeBytes", bytes.length, "sha256", UploadManifest.hash(bytes), "origin", origin))));
    }
 
 

pom.xml

@@ -1,17 +1,20 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <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>
+   <!-- Reactor root AND parent of every module. The release pipeline rewrites only the version property below in THIS file, so it is the single version
+        source of every published module. The root keeps the modules' former parent (qbit-build-parent 2.1.0), so inherited build configuration is unchanged. -->
    <parent>
       <groupId>com.kingsrook</groupId>
       <artifactId>qbit-build-parent</artifactId>
-      <version>2.1.0</version>
+      <version>2.2.1</version>
       <relativePath />
    </parent>
    <groupId>com.kingsrook.qbits</groupId>
-   <artifactId>qbit-mobile-scanners</artifactId>
+   <artifactId>qbit-mobile-scanners-reactor</artifactId>
    <version>${revision}</version>
-   <name>QQQ Mobile Scanners</name>
-   <description>Approved mobile devices and native QQQ barcode capture processes.</description>
+   <packaging>pom</packaging>
+   <name>QQQ Mobile Scanners (reactor)</name>
+   <description>Aggregator for the published Mobile Scanners modules: the base qbit and its optional Record Files integration.</description>
    <url>https://git.kof22.com/QRun-IO/qbit-mobile-scanners</url>
    <scm>
       <connection>scm:git:https://git.kof22.com/QRun-IO/qbit-mobile-scanners.git</connection>
@@ -31,91 +34,41 @@
       </license>
    </licenses>
    <properties>
-      <revision>0.1.0-SNAPSHOT</revision>
+      <revision>0.6.0-SNAPSHOT</revision>
+      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <maven.compiler.release>21</maven.compiler.release>
-      <qqq.version>4.1.0-RC.21</qqq.version>
+      <qqq.version>4.1.0-RC.26</qqq.version>
    </properties>
-   <dependencyManagement>
-      <dependencies>
-         <dependency>
-            <groupId>com.kingsrook.qqq</groupId>
-            <artifactId>qqq-bom-pom</artifactId>
-            <version>${qqq.version}</version>
-            <type>pom</type>
-            <scope>import</scope>
-         </dependency>
-      </dependencies>
-   </dependencyManagement>
-   <dependencies>
-      <dependency>
-         <groupId>com.kingsrook.qqq</groupId>
-         <artifactId>qqq-backend-core</artifactId>
-      </dependency>
-      <dependency>
-         <groupId>com.kingsrook.qqq</groupId>
-         <artifactId>qqq-middleware-javalin</artifactId>
-      </dependency>
-      <dependency>
-         <groupId>com.kingsrook.qqq</groupId>
-         <artifactId>qqq-backend-module-rdbms</artifactId>
-         <scope>test</scope>
-      </dependency>
-      <dependency>
-         <groupId>com.h2database</groupId>
-         <artifactId>h2</artifactId>
-         <version>2.2.224</version>
-         <scope>test</scope>
-      </dependency>
-      <dependency>
-         <groupId>com.kingsrook.qqq</groupId>
-         <artifactId>qqq-backend-module-postgres</artifactId>
-         <scope>test</scope>
-      </dependency>
-      <dependency>
-         <groupId>org.testcontainers</groupId>
-         <artifactId>postgresql</artifactId>
-         <version>1.21.4</version>
-         <scope>test</scope>
-      </dependency>
-      <dependency>
-         <groupId>org.postgresql</groupId>
-         <artifactId>postgresql</artifactId>
-         <version>42.7.14</version>
-         <scope>test</scope>
-      </dependency>
-      <dependency>
-         <groupId>org.junit.jupiter</groupId>
-         <artifactId>junit-jupiter</artifactId>
-         <version>5.11.4</version>
-         <scope>test</scope>
-      </dependency>
-   </dependencies>
+   <!-- Every published module, so one root deploy builds every GAV. demo/ and examples/ are runnable demonstrations with their own coordinates and are intentionally
+        not part of this reactor. Build a subset with -pl <module> -am. -->
+   <modules>
+      <module>base</module>
+      <module>integrations/record-files</module>
+   </modules>
    <build>
       <plugins>
          <plugin>
-            <groupId>org.apache.maven.plugins</groupId>
-            <artifactId>maven-checkstyle-plugin</artifactId>
-            <version>3.6.0</version>
-            <dependencies>
-               <dependency>
-                  <groupId>com.puppycrawl.tools</groupId>
-                  <artifactId>checkstyle</artifactId>
-                  <version>14.3.0</version>
-               </dependency>
-            </dependencies>
+            <!-- Publish consumer POMs with the version resolved (the parent reference and the reactor root itself would otherwise carry the unresolved property). -->
+            <groupId>org.codehaus.mojo</groupId>
+            <artifactId>flatten-maven-plugin</artifactId>
+            <version>1.7.3</version>
             <configuration>
-               <configLocation>checkstyle/checkstyle.xml</configLocation>
-               <consoleOutput>true</consoleOutput>
-               <includeTestSourceDirectory>true</includeTestSourceDirectory>
-               <failOnViolation>true</failOnViolation>
-               <violationSeverity>warning</violationSeverity>
+               <updatePomFile>true</updatePomFile>
+               <flattenMode>ossrh</flattenMode>
             </configuration>
             <executions>
                <execution>
-                  <id>checkstyle</id>
-                  <phase>validate</phase>
+                  <id>flatten</id>
+                  <phase>process-resources</phase>
                   <goals>
-                     <goal>check</goal>
+                     <goal>flatten</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>flatten.clean</id>
+                  <phase>clean</phase>
+                  <goals>
+                     <goal>clean</goal>
                   </goals>
                </execution>
             </executions>