fix(presence): always send viewers, empty after the last leave

When the last viewer left, presence.changed arrived as {"table":"person"}
with no viewers. The registry did put an empty list in the event data,
but core's SSE writer serializes event data with JsonUtils.toJson, whose
NON_EMPTY inclusion drops empty collections, including map values. A
client waiting for viewers kept showing the last person, although
CollaborationPresenceSnapshotV1.viewers is a required array.

The event's viewers list is now a PresenceRegistry.Viewers list whose
serializer reports it is never empty, so the SSE stream sends
"viewers":[]. The snapshot record marks viewers JsonInclude.ALWAYS so it
does not depend on the HTTP layer's inclusion either, and the OpenAPI
extension document now states viewers is non-nullable and always present.

The root cause sits in qqq core (RealtimeStreamSpecV1 serializes with
NON_EMPTY, unlike AbstractJsonEndpointSpec), which also drops other empty
arrays such as record.* fields; this fix covers presence until core does.

Fixes #52

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.circleci/config.yml

@@ -1,60 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-   qqq-orb: kingsrook/qqq-orb@0.6.9
-
-commands:
-   configure-package-install:
-      steps:
-         - run:
-              name: Keep package installation unattended
-              command: |
-                 # These build machines are discarded after the job.
-                 sudo install -d /etc/needrestart/conf.d
-                 printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
-
+  qqq-orb: kingsrook/qqq-orb@0.8
 workflows:
-   test_only:
-      jobs:
-         - qqq-orb/mvn_test_only:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              filters:
-                 branches:
-                    ignore: /(develop|release\/.*)/
-
-   publish_snapshot:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: snapshot
-              filters:
-                 branches:
-                    only: [develop]
-
-   publish_release_candidate:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release_candidate
-              filters:
-                 branches:
-                    only: [/release\/.*/]
-
-   publish_release:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release
-              filters:
-                 branches:
-                    ignore: /.*/
-                 tags:
-                    only: [/^v\d+\.\d+\.\d+$/]
+  setup:
+    jobs:
+    - qqq-orb/generate_pipeline:
+        orb_version: '0.8'
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/

.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+'on':
+  push:
+    branches:
+    - main
+    - develop
+    - release/**
+    - hotfix/**
+  pull_request: {}
+  schedule:
+  - cron: 41 16 * * 0
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  actions: read
+  security-events: write
+  packages: read
+concurrency:
+  group: codeql-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  analyze:
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@c288a8864fe9054f68410e1d78f5863aea4c4d22

.github/workflows/release-rc.yml

@@ -1,25 +1,74 @@
-# Cut the next release candidate (QRun-IO/qqq docs/QRUN-QBIT-REPO-STANDARD.md, C6):
-# run this workflow by hand, or merge a develop PR labelled `release:rc`. It merges develop into
-# the release line and the release/* push runs CircleCI publish_release_candidate.
 name: Release candidate
-
-on:
+'on':
   workflow_dispatch:
     inputs:
       dry_run:
-        description: Print the plan without merging or creating branches
+        description: Plan a cut without changing release state
         type: boolean
         default: false
+      finalize:
+        description: Retry finalization of an existing cut; do not cut another RC
+        type: boolean
+        default: false
+      recover:
+        description: Recover the same published RC after a deployment timeout; never
+          reupload
+        type: boolean
+        default: false
+      circle_build:
+        description: Original Circle publisher build number (recovery only)
+        type: string
+        default: ''
+      merge_sha:
+        description: Existing cut merge_sha (finalize retry only)
+        type: string
+        default: ''
+      bump_sha:
+        description: Existing cut bump_sha (finalize retry only)
+        type: string
+        default: ''
+      branch:
+        description: Existing cut branch (finalize retry only)
+        type: string
+        default: ''
+      version:
+        description: Existing cut version (finalize retry only)
+        type: string
+        default: ''
   pull_request:
-    types: [closed]
-    branches: [develop]
-
+    types:
+    - closed
+    branches:
+    - develop
+  repository_dispatch:
+    types:
+    - qbit-rc-published
 permissions:
   contents: write
-
+  actions: read
+  checks: read
 jobs:
   release-rc:
-    if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release:rc'))
-    uses: QRun-IO/.github/.github/workflows/qbit-release-rc.yml@main
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
+      || (github.event_name == 'pull_request' && github.event.pull_request.merged
+      == true && github.event.pull_request.base.ref == 'develop' && contains(github.event.pull_request.labels.*.name,
+      'release:rc'))
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-release-rc.yml@cc30f599e63c8e41629c99d23395bac1adb8bc44
     with:
-      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false
+        }}
+      finalize: ${{ github.event_name == 'repository_dispatch' || (github.event_name
+        == 'workflow_dispatch' && inputs.finalize) }}
+      recover: ${{ github.event_name == 'workflow_dispatch' && inputs.recover || false
+        }}
+      circle_build: ${{ github.event_name == 'workflow_dispatch' && inputs.circle_build
+        || '' }}
+      merge_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.merge_sha
+        || inputs.merge_sha || '' }}
+      bump_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.bump_sha
+        || inputs.bump_sha || '' }}
+      branch: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch
+        || inputs.branch || '' }}
+      version: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.version
+        || inputs.version || '' }}
+    secrets: inherit

.qqq-ci.yml

@@ -0,0 +1,16 @@
+profile: qbit
+orb_version: '0.8'
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: stable
+test_branch_policy: non-release
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: true

CHANGELOG.md

@@ -13,6 +13,8 @@ All notable changes are documented here, following [Keep a Changelog](https://ke
 
 ### Changed
 
+- UI API extension collaboration 1.1.0 (requires QQQ 4.1.0-RC.15, UI API 1.6.0): operationIds, standard error responses with BasicErrorResponseV1, extension tags and published presence request/snapshot/viewer schemas to resolve dangling references. Retain CollaborationErrorV1 as deprecated.
+
 - Upgrade the default QQQ BOM to `4.1.0-RC.7` from Maven Central.
 - Register the core followers provider for alerts and other qbits, with event preferences, future-mute exclusion, system reads scoped to one record, and caller-owned recipient access checks.
 - Cache favorite/recent record labels only for FULL field access. Resolve comment/share notification labels per recipient with a table-label-and-id fallback. Use the typed core label-access API for email labels as well.
@@ -24,6 +26,9 @@ All notable changes are documented here, following [Keep a Changelog](https://ke
 
 ### Fixed
 
+- QBit metadata reports the Maven artifact version from a filtered resource, including release versions.
+- `presence.changed` events and presence snapshots always carry `viewers`, sending `[]` once the last viewer leaves, as the schema requires (#52).
+
 - Timeline audit summaries read "Edited by Alice Morgan: Title, Total" or "Created by Alice Morgan" instead of "Record was Edited"; detail rows are unchanged.
 - The demo server chooses its user per browser session (`?user=bob`, remembered in a cookie) instead of once per JVM, and sends the person's name to the frontend so it no longer shows Anonymous.
 - The share recipient search and mention candidates no longer offer the caller to themself.

README.md

@@ -410,13 +410,13 @@ The runtime provider adds this field and its search entry where TAGS is enabled.
 
 ## UI API
 
-The producer registers extension `collaboration` version `1.0.0` at
+The producer registers extension `collaboration` version `1.1.0` at
 `/qqq/v1/qbit/collaboration`. It uses the signed-in user's session and existing
 services. Disable registration with `new CollaborationQBitConfig().withUiApi(false)`.
-Presence, shares, tasks, my-work, direct upload and thumbnail routes are not part
-of this extension version.
+Requires QQQ `4.1.0-RC.15` and UI API `1.6.0`. Operations carry stable operationIds,
+the collaboration tag and standard error responses.
 
-All successes return HTTP 200. All bodies have named `Collaboration*V1` schemas
+All successes return HTTP 200. Success and request bodies have named `Collaboration*V1` schemas
 in [the extension contract](src/main/resources/openapi/qqq-v1/collaboration.yaml).
 The server publishes these alongside core at `/qqq/v1/openapi.yaml` and `.json`.
 
@@ -478,9 +478,11 @@ attachment filename; preview requests inline content. QQQ's current OpenAPI
 `Response` model cannot declare the `Location` header, so this contract uses the
 JSON URL alternative consistently.
 
-A missing or invisible parent returns identical `404 {"error":"Not found"}`.
-Missing write permissions return 403; invalid input returns 400 with an `error`
-message through QQQ's exception mapper. Provider/backend failures remain server
+A missing or invisible parent returns 404 with the same `Not found` error message.
+Missing write permissions return 403; invalid input returns 400 through QQQ's
+exception mapper. Errors use `BasicErrorResponseV1` with `error`, `code`, `message`,
+`traceId` and optional `fieldErrors`. `CollaborationErrorV1` remains defined but is
+deprecated since 1.1.0. Provider/backend failures remain server
 errors. Services continue to own author, record-lock and permission checks.
 Mention candidates expose `canRead` as the string enum `"true"`, `"false"`,
 `"unknown"`; unknown does not imply the recipient can read the record.
@@ -636,7 +638,7 @@ New routes, all under `/qqq/v1/qbit/collaboration`:
 | PUT | `/records/{table}/{pk}/assignment` |
 | GET | `/my-work` |
 
-Typed `CollaborationWorkSchemas` describe requests and results. Task PATCH preserves omitted fields, accepts OPEN/DONE/CANCELLED transitions, and permits explicit null for optional fields; null `remindAt` selects the service's due-date default. Assignment PUT replaces owner and assignee; null clears. Invalid input is 400, denied visible-record operations are 403, and missing/invisible parents are 404. Access requests deliberately never inspect parent existence. The extension stays at unreleased **1.0.0**; contract tooling accepts these additions without a bump.
+Typed `CollaborationWorkSchemas` describe requests and results. Task PATCH preserves omitted fields, accepts OPEN/DONE/CANCELLED transitions, and permits explicit null for optional fields; null `remindAt` selects the service's due-date default. Assignment PUT replaces owner and assignee; null clears. Invalid input is 400, denied visible-record operations are 403, and missing/invisible parents are 404. Access requests deliberately never inspect parent existence. The extension is now **1.1.0**, including the UI API 1.6.0 error contract and published presence schemas.
 
 `CollaborationRealtime` publishes `comment.added/updated/deleted`, `attachment.changed`, `tags.changed` and `task.changed` on `record:{table}:{pk}` after commit. Successful notification delivery publishes `notification.created` on `user:{userId}`. Payloads contain identifiers only. `CollaborationFollowersProvider` supplies the core followers SPI for alerts and other consumers. Selectable Tags values remain unavailable because the overlay has no output hook.
 

pom.xml

@@ -120,6 +120,7 @@
             <filtering>true</filtering>
             <includes>
                <include>help/*.yaml</include>
+               <include>qbit-collaboration.properties</include>
             </includes>
          </resource>
          <resource>
@@ -127,6 +128,7 @@
             <filtering>false</filtering>
             <excludes>
                <exclude>help/*.yaml</exclude>
+               <exclude>qbit-collaboration.properties</exclude>
             </excludes>
          </resource>
       </resources>
@@ -223,14 +225,14 @@
    <profiles>
       <!-- Built against qqq 4.1 (QBitMetaDataProducer). Until qbit-build-parent  -->
       <!-- imports the released 4.1 BOM, this profile is active by default and     -->
-      <!-- imports qqq-bom-pom 4.1.0-RC.7 ahead of the parent's 4.0.0 BOM.         -->
+      <!-- imports qqq-bom-pom 4.1.0-RC.15 ahead of the parent's 4.0.0 BOM.         -->
       <profile>
          <id>qqq-snapshot</id>
          <activation>
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.7</qqq.snapshot.version>
+            <qqq.snapshot.version>4.1.0-RC.15</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

src/main/java/com/kingsrook/qbits/collaboration/CollaborationQBitProducer.java

@@ -22,6 +22,9 @@
 package com.kingsrook.qbits.collaboration;
 
 
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Properties;
 import com.kingsrook.qbits.collaboration.app.CollaborationHome;
 import com.kingsrook.qbits.collaboration.attachments.DeleteAttachmentsProcess;
 import com.kingsrook.qbits.collaboration.model.CollaborationTables;
@@ -44,13 +47,41 @@ public class CollaborationQBitProducer implements QBitMetaDataProducer<Collabora
 {
    public static final String GROUP_ID = "com.kingsrook.qbits";
    public static final String ARTIFACT_ID = "qbit-collaboration";
-   public static final String VERSION = "0.1.0";
+   public static final String VERSION = loadVersion();
 
    private CollaborationQBitConfig qBitConfig;
    private String namespace;
 
 
 
+   /*******************************************************************************
+    ** Read the artifact version from the Maven-filtered properties resource.
+    *******************************************************************************/
+   private static String loadVersion()
+   {
+      try(InputStream inputStream = CollaborationQBitProducer.class.getClassLoader().getResourceAsStream("qbit-collaboration.properties"))
+      {
+         if(inputStream == null)
+         {
+            throw new IllegalStateException("Missing qbit-collaboration.properties; build with Maven to generate the artifact version.");
+         }
+         Properties properties = new Properties();
+         properties.load(inputStream);
+         String version = properties.getProperty("version");
+         if(version == null || version.isBlank() || version.contains("${"))
+         {
+            throw new IllegalStateException("Missing or unfiltered version in qbit-collaboration.properties; build with Maven resource filtering.");
+         }
+         return (version);
+      }
+      catch(IOException e)
+      {
+         throw new IllegalStateException("Could not read the artifact version from qbit-collaboration.properties.", e);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Configure the qbit.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/collaboration/api/CollaborationApi.java

@@ -52,7 +52,7 @@ public final class CollaborationApi
     *******************************************************************************/
    public static MiddlewareSpecExtension extension()
    {
-      return (new MiddlewareSpecExtension().withName("collaboration").withSemanticVersion("1.0.0")
+      return (new MiddlewareSpecExtension().withName("collaboration").withSemanticVersion("1.1.0")
          .withDescription("Record collaboration: favorites, recents, attachments, tags, conversations, following, timeline, people and presence")
          .withSpec(PostPresenceSpec.class).withSpec(DeletePresenceSpec.class).withSpec(GetPresenceSpec.class)
          .withSpec(ListFavoritesSpec.class)

src/main/java/com/kingsrook/qbits/collaboration/api/CollaborationJsonSpec.java

@@ -46,6 +46,7 @@ import com.kingsrook.qqq.backend.core.exceptions.QBadRequestException;
 import com.kingsrook.qqq.middleware.javalin.specs.BasicOperation;
 import com.kingsrook.qqq.middleware.javalin.specs.BasicResponse;
 import com.kingsrook.qqq.middleware.javalin.specs.extensions.AbstractJsonEndpointSpec;
+import com.kingsrook.qqq.middleware.javalin.specs.v1.responses.BasicErrorResponseV1;
 import com.kingsrook.qqq.openapi.model.HttpMethod;
 import com.kingsrook.qqq.openapi.model.In;
 import com.kingsrook.qqq.openapi.model.Parameter;
@@ -112,10 +113,10 @@ abstract class CollaborationJsonSpec extends AbstractJsonEndpointSpec
     *******************************************************************************/
    static List<BasicResponse> errors()
    {
-      return (List.of(new BasicResponse(HttpStatus.BAD_REQUEST, "Invalid input", "CollaborationErrorV1"),
-         new BasicResponse(HttpStatus.UNAUTHORIZED, "Sign in required", "CollaborationErrorV1"),
-         new BasicResponse(HttpStatus.FORBIDDEN, "Permission denied", "CollaborationErrorV1"),
-         new BasicResponse(HttpStatus.NOT_FOUND, "Not found (including invisible parents)", "CollaborationErrorV1")));
+      return (List.of(new BasicResponse(HttpStatus.BAD_REQUEST, "Invalid input", BasicErrorResponseV1.class.getSimpleName()),
+         new BasicResponse(HttpStatus.UNAUTHORIZED, "Sign in required", BasicErrorResponseV1.class.getSimpleName()),
+         new BasicResponse(HttpStatus.FORBIDDEN, "Permission denied", BasicErrorResponseV1.class.getSimpleName()),
+         new BasicResponse(HttpStatus.NOT_FOUND, "Not found (including invisible parents)", BasicErrorResponseV1.class.getSimpleName())));
    }
 
    /*******************************************************************************

src/main/java/com/kingsrook/qbits/collaboration/api/CollaborationPresenceSchemas.java

@@ -24,6 +24,7 @@ package com.kingsrook.qbits.collaboration.api;
 import java.util.List;
 import java.util.Map;
 import java.util.TreeMap;
+import com.fasterxml.jackson.annotation.JsonInclude;
 import com.kingsrook.qbits.collaboration.presence.PresenceRegistry;
 import com.kingsrook.qqq.middleware.javalin.schemabuilder.ToSchema;
 import com.kingsrook.qqq.openapi.model.Schema;
@@ -80,9 +81,10 @@ public final class CollaborationPresenceSchemas
    }
 
    /*******************************************************************************
-    ** The snapshot is also the data shape of presence.changed events.
+    ** The snapshot is also the data shape of presence.changed events. Viewers are
+    ** included even when empty, whatever inclusion the serializer defaults to.
     *******************************************************************************/
-   public record CollaborationPresenceSnapshotV1(String table, String pk, List<PresenceRegistry.Viewer> viewers) implements ToSchema
+   public record CollaborationPresenceSnapshotV1(String table, String pk, @JsonInclude(JsonInclude.Include.ALWAYS) List<PresenceRegistry.Viewer> viewers) implements ToSchema
    {
       /*******************************************************************************
        ** A table snapshot deliberately excludes record ids and focused field names.
@@ -93,7 +95,7 @@ public final class CollaborationPresenceSchemas
          return (new Schema().withType(Type.OBJECT).withDescription("Live viewers, merged across tabs; presence.changed uses this payload.")
             .withProperties(new TreeMap<>(Map.of(
                "table", text("Parent table name.", false), "pk", text("Record key; absent for table events.", true),
-               "viewers", new Schema().withType(Type.ARRAY).withItems(new Schema().withRefToSchema("CollaborationPresenceViewerV1"))))));
+               "viewers", new Schema().withType(Type.ARRAY).withDescription("Live viewers; always present, empty once the last viewer leaves.").withNullable(false).withItems(new Schema().withRefToSchema("CollaborationPresenceViewerV1"))))));
       }
    }
 

src/main/java/com/kingsrook/qbits/collaboration/api/CollaborationSchemas.java

@@ -514,7 +514,7 @@ public final class CollaborationSchemas
       @Override
       public Schema toSchema()
       {
-         return (new Schema().withType(Type.OBJECT).withDescription("Standard QQQ error response.").withProperties(new TreeMap<>(Map.ofEntries(
+         return (new Schema().withType(Type.OBJECT).withDescription("Deprecated since 1.1.0: errors use BasicErrorResponseV1.").withProperties(new TreeMap<>(Map.ofEntries(
             Map.entry("error", new Schema().withType(Type.STRING).withDescription("Human-readable reason the operation failed.").withNullable(true))))));
       }
    }
@@ -714,6 +714,10 @@ public final class CollaborationSchemas
       schemas.put("CollaborationCommentPostRequestV1", new CollaborationCommentPostRequestV1(null, null, null).toSchema());
       schemas.put("CollaborationCommentEditRequestV1", new CollaborationCommentEditRequestV1(null).toSchema());
       schemas.put("CollaborationFollowRequestV1", new CollaborationFollowRequestV1(null, null).toSchema());
+      schemas.put("CollaborationPresenceRequestV1", new CollaborationPresenceSchemas.CollaborationPresenceRequestV1(null, null, null, null, null).toSchema());
+      schemas.put("CollaborationPresenceLeaveV1", new CollaborationPresenceSchemas.CollaborationPresenceLeaveV1(null, null, null).toSchema());
+      schemas.put("CollaborationPresenceSnapshotV1", new CollaborationPresenceSchemas.CollaborationPresenceSnapshotV1(null, null, null).toSchema());
+      schemas.put("CollaborationPresenceViewerV1", new CollaborationPresenceSchemas.CollaborationPresenceViewerV1(null, null, null, null).toSchema());
       schemas.putAll(CollaborationWorkSchemas.components());
       return (schemas);
    }

src/main/java/com/kingsrook/qbits/collaboration/presence/PresenceRegistry.java

@@ -21,6 +21,7 @@
 
 package com.kingsrook.qbits.collaboration.presence;
 
+import java.io.IOException;
 import java.io.Serializable;
 import java.time.Clock;
 import java.util.ArrayList;
@@ -33,6 +34,10 @@ import java.util.WeakHashMap;
 import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.TimeUnit;
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.StdSerializer;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.realtime.RealtimeBus;
@@ -323,7 +328,7 @@ public final class PresenceRegistry implements AutoCloseable
       {
          data.put("pk", pk);
       }
-      ArrayList<LinkedHashMap<String, Serializable>> viewers = new ArrayList<>();
+      Viewers viewers = new Viewers();
       synchronized(this)
       {
          for(Viewer viewer : snapshotInternal(table, pk))
@@ -340,6 +345,61 @@ public final class PresenceRegistry implements AutoCloseable
       bus.publish(new RealtimeMessage().withChannel(channel).withEvent("presence.changed").withData(data));
    }
 
+   /*******************************************************************************
+    ** Event viewers list that is never omitted: the SSE writer serializes event data
+    ** with NON_EMPTY inclusion, which would drop an empty list, but the schema
+    ** declares viewers a required array, so the last leave must send [] (#52).
+    *******************************************************************************/
+   @JsonSerialize(using = ViewersSerializer.class)
+   public static final class Viewers extends ArrayList<LinkedHashMap<String, Serializable>>
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Writes each viewer with the caller's mapper settings and reports never empty.
+    *******************************************************************************/
+   public static final class ViewersSerializer extends StdSerializer<Viewers>
+   {
+      /*******************************************************************************
+       ** Jackson instantiates the serializer reflectively.
+       *******************************************************************************/
+      public ViewersSerializer()
+      {
+         super(Viewers.class);
+      }
+
+
+
+      /*******************************************************************************
+       ** Always an array, including the empty array after the last viewer leaves.
+       *******************************************************************************/
+      @Override
+      public void serialize(Viewers viewers, JsonGenerator generator, SerializerProvider provider) throws IOException
+      {
+         generator.writeStartArray(viewers, viewers.size());
+         for(LinkedHashMap<String, Serializable> viewer : viewers)
+         {
+            provider.defaultSerializeValue(viewer, generator);
+         }
+         generator.writeEndArray();
+      }
+
+
+
+      /*******************************************************************************
+       ** NON_EMPTY inclusion consults this; an empty viewer list is still a value.
+       *******************************************************************************/
+      @Override
+      public boolean isEmpty(SerializerProvider provider, Viewers viewers)
+      {
+         return (false);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Release listeners and timer on host shutdown or in tests.
     *******************************************************************************/

src/main/resources/qbit-collaboration.properties

@@ -0,0 +1 @@
+version=${project.version}

src/test/java/com/kingsrook/qbits/collaboration/CollaborationApiContractTest.java

@@ -29,6 +29,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule;
 import com.kingsrook.qqq.middleware.javalin.specs.extensions.MiddlewareSpecExtensionsMetaData;
 import com.kingsrook.qqq.middleware.javalin.specs.v1.MiddlewareVersionV1;
+import com.kingsrook.qqq.middleware.javalin.specs.v1.responses.BasicErrorResponseV1;
 import com.kingsrook.qqq.middleware.javalin.tools.UiApiContract;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -56,7 +57,7 @@ class CollaborationApiContractTest
       assertThat(UiApiContract.check(generated, Files.readString(path), null, 1,
          "mvnw.cmd -o -q -Dtest=CollaborationApiContractTest -Dcollaboration.openapi.update=true test")).isEmpty();
       var model = version.generateExtensionOpenAPIModel("qqq", extension);
-      assertThat(model.getComponents().getSchemas().keySet()).allMatch(name -> name.startsWith("Collaboration"));
+      assertThat(model.getComponents().getSchemas().keySet()).allMatch(name -> name.startsWith("Collaboration") || name.equals(BasicErrorResponseV1.class.getSimpleName()));
       assertThat(model.getPaths().keySet()).allMatch(pathName -> pathName.startsWith("/qqq/v1/qbit/collaboration/"));
       assertThat(generated).contains("multipart/form-data", "format: \"binary\"", "clients follow url", "nextCursor");
       assertThat(extension.getSpecs()).hasSize(45);

src/test/java/com/kingsrook/qbits/collaboration/CollaborationApiHttpTest.java

@@ -37,6 +37,7 @@ import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
 import com.kingsrook.qbits.collaboration.attachments.AttachmentStorage;
 import com.kingsrook.qbits.objectstorage.api.PresignGet;
 import com.kingsrook.qbits.objectstorage.api.PutRequest;
@@ -431,8 +432,16 @@ class CollaborationApiHttpTest extends PersonalServiceFixture
          HttpResponse<String> hidden = request("GET", "/records/document/3/" + feature, null, "alice");
          HttpResponse<String> absent = request("GET", "/records/document/999/" + feature, null, "alice");
          assertThat(hidden.statusCode()).isEqualTo(404);
-         assertThat(hidden.body()).isEqualTo(absent.body());
-         assertThat(json(hidden, 404).get("error").asText()).isEqualTo("Not found");
+         ObjectNode hiddenError = (ObjectNode) json(hidden, 404);
+         ObjectNode absentError = (ObjectNode) json(absent, 404);
+         assertThat(hiddenError.path("traceId").asText()).isNotBlank();
+         assertThat(absentError.path("traceId").asText()).isNotBlank();
+         hiddenError.remove("traceId");
+         absentError.remove("traceId");
+         assertThat(hiddenError).isEqualTo(absentError);
+         assertThat(hiddenError.path("error").asText()).isEqualTo("Not found");
+         assertThat(hiddenError.path("code").asText()).isEqualTo("NOT_FOUND");
+         assertThat(hiddenError.path("message").asText()).isEqualTo("Not found");
       }
       assertError(404, "POST", "/records/document/3/comments", "not json", "alice");
       assertError(404, "GET", "/mentions/candidates?table=document&pk=3", null, "alice");
@@ -500,15 +509,19 @@ class CollaborationApiHttpTest extends PersonalServiceFixture
       JsonNode version = json(client.send(HttpRequest.newBuilder(URI.create(serverUrl + "/qqq/v1/version")).GET().build(),
          HttpResponse.BodyHandlers.ofString()), 200);
       assertThat(version.at("/extensions/0/name").asText()).isEqualTo("collaboration");
-      assertThat(version.at("/extensions/0/version").asText()).isEqualTo("1.0.0");
+      assertThat(version.at("/extensions/0/version").asText()).isEqualTo("1.1.0");
    }
 
    /*******************************************************************************
-    ** Framework errors always contain a human-readable error property.
+    ** Framework errors include the standard message, code and request trace.
     *******************************************************************************/
    private void assertError(int status, String method, String path, String body, String caller) throws Exception
    {
-      assertThat(json(request(method, path, body, caller), status).get("error").asText()).isNotBlank();
+      var error = json(request(method, path, body, caller), status);
+      assertThat(error.path("error").asText()).isNotBlank();
+      assertThat(error.path("code").asText()).isNotBlank();
+      assertThat(error.path("message").asText()).isNotBlank();
+      assertThat(error.path("traceId").asText()).isNotBlank();
    }
 
    /*******************************************************************************

src/test/java/com/kingsrook/qbits/collaboration/CollaborationTablesGuardrailTest.java

@@ -146,7 +146,7 @@ class CollaborationTablesGuardrailTest extends PersonalServiceFixture
       assertThat(HelpBundles.of(instance).getBundles()).singleElement().satisfies(bundle ->
       {
          assertThat(bundle.getId()).isEqualTo("qbit-collaboration");
-         assertThat(bundle.getVersion()).as("the help bundle carries the artifact version").isEqualTo(System.getProperty("qbit.artifactVersion"));
+         assertThat(bundle.getVersion()).as("the help bundle carries the artifact version").isEqualTo(System.getProperty("qbit.artifactVersion")).isEqualTo(CollaborationQBitProducer.VERSION);
          assertThat(bundle.getEntries()).anyMatch(entry -> entry.getKey().equals("app:collaboration;slot:help"));
       });
    }

src/test/java/com/kingsrook/qbits/collaboration/CollaborationTest.java

@@ -146,7 +146,7 @@ class CollaborationTest
       assertThat(producer.isEnabled()).isTrue();
       assertThat(producer.getQBitConfig()).isSameAs(config);
       assertThat(producer.getNamespace()).isEqualTo("collaboration");
-      assertThat(producer.getQBitMetaData().getVersion()).isEqualTo("0.1.0");
+      assertThat(producer.getQBitMetaData().getVersion()).isEqualTo(System.getProperty("qbit.artifactVersion")).isEqualTo(CollaborationQBitProducer.VERSION);
       assertThat(producer.getQBitMetaData().getArtifactId()).isEqualTo("qbit-collaboration");
       assertThat(config.getDefaultBackendNameForTables()).isEqualTo("memory");
       assertThat(config.getAdminApp()).isTrue();

src/test/java/com/kingsrook/qbits/collaboration/PresenceTest.java

@@ -24,8 +24,10 @@ package com.kingsrook.qbits.collaboration;
 import java.time.Clock;
 import java.time.Instant;
 import java.time.ZoneId;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.concurrent.CopyOnWriteArrayList;
+import com.kingsrook.qbits.collaboration.api.CollaborationPresenceSchemas;
 import com.kingsrook.qbits.collaboration.presence.PresenceRegistry;
 import com.kingsrook.qbits.collaboration.presence.PresenceService;
 import com.kingsrook.qbits.collaboration.app.CollaborationHome;
@@ -36,6 +38,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeature
 import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeaturesMetaData;
 import com.kingsrook.qqq.backend.core.realtime.InMemoryRealtimeBus;
 import com.kingsrook.qqq.backend.core.realtime.RealtimeMessage;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -87,6 +90,46 @@ class PresenceTest extends PersonalServiceFixture
       }
    }
 
+   /*******************************************************************************
+    ** The last leave still sends viewers: the SSE writer and the HTTP snapshot must
+    ** both carry an empty array, never omit the field (#52).
+    *******************************************************************************/
+   @Test
+   void lastLeaveSendsEmptyViewers() throws Exception
+   {
+      var clock = new MutableClock();
+      try(var bus = new InMemoryRealtimeBus(); var registry = new PresenceRegistry(bus, clock, PresenceRegistry.MAX_ENTRIES))
+      {
+         List<RealtimeMessage> events = new CopyOnWriteArrayList<>();
+         bus.subscribe(events::add);
+         registry.heartbeat("bob", "Bob", "one", "person", null, "VIEWING", null);
+         registry.heartbeat("bob", "Bob", "one", "person", "7", "EDITING", "name");
+         registry.leave("bob", "one", "person", null);
+         registry.leave("bob", "one", "person", "7");
+         assertThat(registry.snapshot("person", null)).isEmpty();
+
+         for(String channel : List.of("table:person", "record:person:7"))
+         {
+            RealtimeMessage last = events.stream().filter(event -> event.getChannel().equals(channel) && event.getEvent().equals("presence.changed")).reduce((first, second) -> second).orElseThrow();
+            assertThat(last.getData()).containsKey("viewers");
+            assertThat((List<?>) last.getData().get("viewers")).isEmpty();
+
+            ///////////////////////////////////////////////////////////////////////
+            // the realtime hub copies the data map and writes it with toJson,   //
+            // whose NON_EMPTY inclusion used to drop the empty viewers list     //
+            ///////////////////////////////////////////////////////////////////////
+            String json = JsonUtils.toJson(new LinkedHashMap<>(last.getData()));
+            assertThat(JsonUtils.toJSONObject(json).getJSONArray("viewers").length()).isZero();
+         }
+
+         String occupied = JsonUtils.toJson(events.stream().filter(event -> event.getChannel().equals("record:person:7")).findFirst().orElseThrow().getData());
+         assertThat(JsonUtils.toJSONObject(occupied).getJSONArray("viewers").getJSONObject(0).getString("fieldName")).isEqualTo("name");
+
+         var snapshot = new CollaborationPresenceSchemas.CollaborationPresenceSnapshotV1("person", null, registry.snapshot("person", null));
+         assertThat(JsonUtils.toJSONObject(JsonUtils.toJson(snapshot)).getJSONArray("viewers").length()).isZero();
+      }
+   }
+
    /*******************************************************************************
     ** At capacity, existing leases renew while new targets are refused on both pods.
     *******************************************************************************/