Merge pull request 'perf: keep the access fingerprint for the request and read rule rows once per change' (#41 ) from perf/request-scoped-resolver-and-cached-rules into develop

perf: keep the access fingerprint for the request and read rule rows once per change
Core asks the field access resolver for its fingerprint before every field decision (FieldAccessHelper.getDecision), that is once per field of every record of a result and of every table in the metaData document. Each call recomputed it: a JSON key, a permission lookup for every table, another JSON document and a digest. Core also asks for the retention rules of a field on every audited field and every filter criterion, and each question was a query. - getAccessFingerprint keeps its value in the request context (QContext) and returns it while the session, its permission set, the channel, the policy and classification versions are unchanged and no active break-glass grant has expired. Nothing outlives the request. - RetentionRules.active answers from the active rules the runtime read once (SecuredDataRuntime.activeRetentionRules). A rule write clears them after commit; a thread that edits rules inside a transaction reads its own edits. - Policy, classification and retention changes are announced on QQQ's cluster bus (ClusterCaches, memo-invalidate), so every node reads again. Before, the versions were node-local and another node kept old rules until restart. - No node uses rule rows older than 30 seconds without reading them again (the safety net for a lost event). - A read that fails throws and replaces nothing: never an empty rule list. Measured in one JVM with GG Forge's composed instance (222 tables, secured data and collaboration wired, in-memory backend, platform administrator), released 0.1.0-RC.4 against this change, same machine, back to back: metaData request 866.6 ms to 125.3 ms (930 MB to 74 MB allocated, 96 to 34 queries); a 300-row list 1,566 ms to 24 ms; a 27-row list 174 to 230 ms down to 13 to 17 ms; queries per list 23 to 8. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 21:37:13 +00:00 · 2026-11-10 15:22:22 -06:00 · 2026-11-07 18:16:02 +00:00 · 2026-11-07 18:08:54 +00:00 · 2026-11-06 16:10:31 +00:00 · 2026-11-06 14:13:29 +00:00
18 changed files with 918 additions and 100 deletions
@@ -1,65 +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:
+  setup:
    jobs:
-      - qqq-orb/mvn_test_only:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          filters:
-            branches:
-              ignore: /(develop|release/.*|integration.*)/
-            tags:
-              only: []
-
-  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+$/ ]
+    - qqq-orb/generate_pipeline:
+        orb_version: '0.8'
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/
@@ -0,0 +1,7 @@
+name: build
+on:
+  push:
+jobs:
+  maven:
+    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/maven.yaml@v1
+    secrets: inherit
@@ -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
@@ -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
@@ -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-no-integration
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: true
@@ -4,6 +4,12 @@ All notable changes are documented here, following [Keep a Changelog](https://ke

 ## [Unreleased]

+### Fixed: access-log lifecycle
+- The access-log worker and JVM shutdown hook hold the logger weakly, so an instance the host drops (tests, reloads) can be collected; its worker stops at the next tick.
+- `withRegisterShutdownHook(false)` for hosts that call `SecuredDataRuntime.close()` themselves; `SecuredDataAccessLogger.isWorkerRunning()`.
+- Virtual (computed) fields resolve through the table classification instead of throwing (#18).
+- Idle access-log ticks open no context, so the worker never validates an unfinished host instance, and a failed tick no longer stops the worker (#18).
+
 ### Changed: UI API 1.6.0
 - UI API extension secured-data 1.1.0 (requires QQQ 4.1.0-RC.15, UI API 1.6.0): operationIds, standard error responses with BasicErrorResponseV1, extension tags, and retained SecuredDataErrorV1 schema deprecated since 1.1.0.

@@ -101,7 +101,7 @@ Policy/break-glass caches are bounded per instance and keyed by relevant user pe

 The extra `search_value_fingerprints` TEXT column persists JSON arrays of HMAC-SHA256 fingerprints for distinct-value detection after restarts and across nodes. Use a shared secret key supplier on multi-node deployments; the default is a random per-JVM key, so historical fingerprints from another JVM/key cannot be compared reliably.

-One daemon worker drains a bounded queue as a system session. Enqueueing does not wait for persistence. Full queues and failed writes warn without values and increment `getDroppedCount()`. The app can expose this counter later. Explicitly call the instance's `SecuredDataRuntime.close()` at host shutdown; a JVM shutdown hook also drains accepted rows. An abrupt process crash can lose queued rows.
+One daemon worker drains a bounded queue as a system session. Enqueueing does not wait for persistence. Full queues and failed writes warn without values and increment `getDroppedCount()`. The app can expose this counter later. Explicitly call the instance's `SecuredDataRuntime.close()` at host shutdown; a JVM shutdown hook also drains accepted rows unless `withRegisterShutdownHook(false)` turns it off (hosts that close the runtime themselves). Neither the worker nor the hook holds the instance strongly: an instance the host drops (tests, reloads) can be collected, and its worker stops at the next tick. An abrupt process crash can lose queued rows.

 Flagged rows raise the optional alerts producer signal `secured_data.enumeration`, deduplicated by `secured_data.enumeration:<user>:<table>.<field>:<UTC date>`. RC.5 already provides `QAlerts`; without an installed sink it logs the signal. Its catalog validator rejects underscores in type names, so this mandated type is sent through the producer without catalog registration until that core restriction is reconciled. No values or fingerprints are sent to the alert sink.

@@ -144,6 +144,7 @@ The classification field picker uses CUSTOM possible values, reading `table_name
 | `withFingerprintKeySupplier(Supplier<byte[]>)` | Random 32-byte JVM key; supplied key must be at least 16 bytes |
 | `withAccessLogQueueCapacity(int)` | 4096 rows |
 | `withAccessLogFlushIntervalMillis(long)` | 250 ms |
+| `withRegisterShutdownHook(boolean)` | true; JVM hook that drains the access log at shutdown |
 | `withExactMatchPerHour(int)` | 20; zero disables |
 | `withMissAlertConsecutive(int)` | 5; zero disables |
 | `withDistinctValueAlert(int)` | 15; zero disables |
@@ -22,8 +22,9 @@
 <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 http://maven.apache.org/xsd/maven-4.0.0.xsd">

   <properties>
+      <qqq.version>4.1.0-RC.26</qqq.version> <!-- feeds qbit-build-parent's qqq-bom-pom import -->
      <!-- QQQ 4.1.0-RC.15 ships UI API 1.6.0, field access and audit value protection -->
-      <qqq.snapshot.version>4.1.0-RC.15</qqq.snapshot.version>
+      <qqq.snapshot.version>4.1.0-RC.26</qqq.snapshot.version>
      <revision>0.1.0-SNAPSHOT</revision>
      <maven.compiler.source>21</maven.compiler.source>
      <maven.compiler.target>21</maven.compiler.target>
@@ -34,7 +35,7 @@
   <parent>
      <groupId>com.kingsrook</groupId>
      <artifactId>qbit-build-parent</artifactId>
-      <version>2.0.0</version>
+      <version>2.2.1</version>
   </parent>

   <groupId>com.kingsrook.qbits</groupId>
@@ -92,7 +93,7 @@
      <dependency>
         <groupId>com.kingsrook.qqq</groupId>
         <artifactId>qqq-frontend-next</artifactId>
-         <version>1.0.0-RC.14</version>
+         <version>1.0.0-RC.38</version>
         <scope>test</scope>
      </dependency>
      <dependency>
@@ -21,6 +21,7 @@
 package com.kingsrook.qbits.secureddata;


+import java.lang.ref.WeakReference;
 import java.time.Instant;
 import java.time.temporal.ChronoUnit;
 import java.util.ArrayDeque;
@@ -90,7 +91,12 @@ public class SecuredDataAccessLogger implements AutoCloseable


   /*******************************************************************************
-    ** One daemon drains this instance's queue; the JVM hook flushes on shutdown.
+    ** One daemon drains this instance's queue; the optional JVM hook flushes on
+    ** shutdown. Neither holds the logger strongly: once the host drops its
+    ** instance (a test, a reloaded instance), the logger, runtime and instance
+    ** can be collected, and the worker stops at its next tick. Hosts that close
+    ** the runtime themselves can turn the hook off
+    ** (SecuredDataQBitConfig.withRegisterShutdownHook(false)).
    *******************************************************************************/
   public SecuredDataAccessLogger(QInstance instance, SecuredDataRuntime runtime)
   {
@@ -103,10 +109,69 @@ public class SecuredDataAccessLogger implements AutoCloseable
         thread.setDaemon(true);
         return (thread);
      });
+      WeakReference<SecuredDataAccessLogger> self = new WeakReference<>(this);
      long interval = runtime.config().getAccessLogFlushIntervalMillis();
-      worker.scheduleWithFixedDelay(this::flush, interval, interval, TimeUnit.MILLISECONDS);
-      shutdownHook = new Thread(this::close, "secured-data-access-log-shutdown");
-      Runtime.getRuntime().addShutdownHook(shutdownHook);
+      worker.scheduleWithFixedDelay(new WeakTick(self, worker), interval, interval, TimeUnit.MILLISECONDS);
+      shutdownHook = runtime.config().getRegisterShutdownHook() ? new Thread(new WeakClose(self), "secured-data-access-log-shutdown") : null;
+      if(shutdownHook != null)
+      {
+         Runtime.getRuntime().addShutdownHook(shutdownHook);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The worker's task, holding the logger weakly: when the logger has been
+    ** collected the worker shuts itself down.
+    *******************************************************************************/
+   private record WeakTick(WeakReference<SecuredDataAccessLogger> logger, ScheduledExecutorService worker) implements Runnable
+   {
+      /*******************************************************************************
+       ** Drain, or stop once the logger is gone.
+       *******************************************************************************/
+      @Override
+      public void run()
+      {
+         SecuredDataAccessLogger target = logger.get();
+         if(target == null)
+         {
+            worker.shutdown();
+            return;
+         }
+         target.scheduledFlush();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The JVM shutdown hook, holding the logger weakly.
+    *******************************************************************************/
+   private record WeakClose(WeakReference<SecuredDataAccessLogger> logger) implements Runnable
+   {
+      /*******************************************************************************
+       ** Drain accepted rows at JVM shutdown, if the logger still exists.
+       *******************************************************************************/
+      @Override
+      public void run()
+      {
+         SecuredDataAccessLogger target = logger.get();
+         if(target != null)
+         {
+            target.close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether the background worker is still running (false after close).
+    *******************************************************************************/
+   public boolean isWorkerRunning()
+   {
+      return (!worker.isShutdown());
   }


@@ -332,13 +397,38 @@ public class SecuredDataAccessLogger implements AutoCloseable



+   /*******************************************************************************
+    ** The worker's tick. An exception would cancel every later run of a
+    ** scheduled task, so a failed drain is logged (value-free) and retried on
+    ** the next tick; the rows stay queued.
+    *******************************************************************************/
+   void scheduledFlush()
+   {
+      try
+      {
+         flush();
+      }
+      catch(RuntimeException e)
+      {
+         LOG.warn("Unable to drain the secured-data access log; retrying on the next tick");
+      }
+   }
+
+
+
   /*******************************************************************************
    ** Drain safely both from the worker and explicit test/host shutdown calls.
+    ** An empty queue opens no context: QContext validates an unvalidated
+    ** instance, and the worker starts while the host is still building it.
    *******************************************************************************/
   public void flush()
   {
      synchronized(flushLock)
      {
+         if(queue.isEmpty())
+         {
+            return;
+         }
         QContext.withTemporaryContext(new CapturedContext(instance, new QSystemUserSession(instance)), () ->
         {
            PendingLog pending;
@@ -463,7 +553,7 @@ public class SecuredDataAccessLogger implements AutoCloseable
      }
      worker.shutdown();
      flush();
-      if(Thread.currentThread() != shutdownHook)
+      if(shutdownHook != null && Thread.currentThread() != shutdownHook)
      {
         try
         {
@@ -54,7 +54,11 @@ public final class SecuredDataClassifications
      {
         return (DataClassification.valueOf(row.getValueString("classification")));
      }
-      QFieldMetaData field = table.getField(fieldName);
+      ////////////////////////////////////////////////////////////////////
+      // getFields, not getField: a virtual field is not in the map and  //
+      // getField throws, while it still takes the table classification //
+      ////////////////////////////////////////////////////////////////////
+      QFieldMetaData field = table.getFields() == null || fieldName == null ? null : table.getFields().get(fieldName);
      DataClassification classification = field == null ? null : SecuredDataMetadata.classification(table, field);
      return (classification == null ? SecuredDataMetadata.classification(table, null) : classification);
   }
@@ -115,6 +115,7 @@ public class SecuredDataQBitConfig implements QBitConfig
   private Clock clock = Clock.systemUTC();
   private int accessLogQueueCapacity = 4096;
   private long accessLogFlushIntervalMillis = 250;
+   private boolean registerShutdownHook = true;
   private int exactMatchPerHour = 20;
   private int missAlertConsecutive = 5;
   private int distinctValueAlert = 15;
@@ -216,6 +217,29 @@ public class SecuredDataQBitConfig implements QBitConfig



+   /*******************************************************************************
+    ** Whether the access logger registers a JVM shutdown hook that drains
+    ** accepted rows (default true). Hosts that call SecuredDataRuntime.close()
+    ** from their own shutdown sequence turn it off.
+    *******************************************************************************/
+   public boolean getRegisterShutdownHook()
+   {
+      return (registerShutdownHook);
+   }
+
+
+
+   /*******************************************************************************
+    ** Configure registerShutdownHook.
+    *******************************************************************************/
+   public SecuredDataQBitConfig withRegisterShutdownHook(boolean registerShutdownHook)
+   {
+      this.registerShutdownHook = registerShutdownHook;
+      return (this);
+   }
+
+
+
   /*******************************************************************************
    ** Configure accessLogFlushIntervalMillis.
    *******************************************************************************/
@@ -75,9 +75,13 @@ public class SecuredDataResolver implements FieldAccessResolverInterface
   }

   private long cachedVersion;
+   private long policiesLoadedAt;
   private List<QRecord> policies = List.of();
   private final Map<String, UserState> users = new HashMap<>();

+   /** Request-scoped (QContext) holder of the access fingerprint. */
+   private static final String FINGERPRINT_KEY = SecuredDataResolver.class.getName() + ".accessFingerprint";
+


   /*******************************************************************************
@@ -292,11 +296,13 @@ public class SecuredDataResolver implements FieldAccessResolverInterface
   private synchronized UserState state()
   {
      long version = runtime.policyVersion();
-      if(cachedVersion != version)
+      if(cachedVersion != version || SecuredDataRuntime.tooOld(policiesLoadedAt))
      {
+         long loadedAt = System.nanoTime();
         policies = List.copyOf(SystemWrites.query(SecuredDataTables.POLICY, new QQueryFilter()));
         users.clear();
         cachedVersion = version;
+         policiesLoadedAt = loadedAt;
      }
      QSession session = QContext.getQSession();
      TreeSet<String> held = new TreeSet<>();
@@ -308,7 +314,7 @@ public class SecuredDataResolver implements FieldAccessResolverInterface
            held.add(permission);
         }
      }
-      String key = JsonUtils.toJson(List.of(userId(), held));
+      String key = userId() + '\u0000' + String.join("\u0000", held);
      UserState state = users.get(key);
      if(state == null)
      {
@@ -356,11 +362,82 @@ public class SecuredDataResolver implements FieldAccessResolverInterface
    ** Stable across unrelated permissions/records; includes channel and exact expiry.
    *******************************************************************************/
   @Override
-   public synchronized String getAccessFingerprint()
+   public String getAccessFingerprint()
   {
-      state();
-      TreeSet<String> relevant = new TreeSet<>();
+      /////////////////////////////////////////////////////////////////////////////
+      // core asks for the fingerprint before every field decision (once per     //
+      // field of every record of a result), so the value is kept for the        //
+      // request - and only while everything it is derived from is unchanged     //
+      /////////////////////////////////////////////////////////////////////////////
      QSession session = QContext.getQSession();
+      String channel = Objects.requireNonNullElse(SecuredDataMetadata.channel(session), "");
+      Instant now = runtime.config().getClock().instant();
+      RequestFingerprint kept = QContext.getObject(FINGERPRINT_KEY, RequestFingerprint.class).orElse(null);
+      if(kept != null && kept.matches(this, session, channel, runtime.policyVersion(), runtime.classificationVersion(), now))
+      {
+         return (kept.value());
+      }
+      RequestFingerprint computed = computeAccessFingerprint(session, channel, now);
+      QContext.setObject(FINGERPRINT_KEY, computed);
+      return (computed.value());
+   }
+
+
+
+   /*******************************************************************************
+    ** The fingerprint and what it was derived from. It stops matching when the
+    ** session, its permissions, the channel, a policy or classification version
+    ** changes, or when the first active break-glass grant expires.
+    *******************************************************************************/
+   private record RequestFingerprint(int resolver, QSession session, int permissionsIdentity, int permissionCount, String channel, long policyVersion,
+      long classificationVersion, Instant validUntil, String value) implements Serializable
+   {
+      /*******************************************************************************
+       ** Whether the kept value is still the one a fresh computation would give.
+       *******************************************************************************/
+      boolean matches(SecuredDataResolver owner, QSession current, String currentChannel, long currentPolicyVersion, long currentClassificationVersion, Instant now)
+      {
+         return (resolver == System.identityHashCode(owner) && session == current && permissionsIdentity == identityOfPermissions(current) && permissionCount == countOfPermissions(current)
+            && channel.equals(currentChannel) && policyVersion == currentPolicyVersion && classificationVersion == currentClassificationVersion && now.isBefore(validUntil));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The permission set object of a session (it is replaced, not edited, when a
+    ** session is given new permissions).
+    *******************************************************************************/
+   private static int identityOfPermissions(QSession session)
+   {
+      return (session == null || session.getPermissions() == null ? 0 : System.identityHashCode(session.getPermissions()));
+   }
+
+
+
+   /*******************************************************************************
+    ** How many permissions a session holds (an edit in place changes it).
+    *******************************************************************************/
+   private static int countOfPermissions(QSession session)
+   {
+      return (session == null || session.getPermissions() == null ? -1 : session.getPermissions().size());
+   }
+
+
+
+   /*******************************************************************************
+    ** Stable across unrelated permissions/records; includes channel and exact expiry.
+    *******************************************************************************/
+   private synchronized RequestFingerprint computeAccessFingerprint(QSession session, String channel, Instant now)
+   {
+      /////////////////////////////////////////////////////////////////////////////
+      // versions are read before the rows they describe, so a change during the //
+      // computation leaves a kept value that no longer matches                   //
+      /////////////////////////////////////////////////////////////////////////////
+      long policyVersion = runtime.policyVersion();
+      long classificationVersion = runtime.classificationVersion();
+      TreeSet<String> relevant = new TreeSet<>();
+      List<QRecord> breakGlass = state().breakGlass();
      for(QRecord row : policies)
      {
         String permission = row.getValueString("permission_name");
@@ -380,12 +457,15 @@ public class SecuredDataResolver implements FieldAccessResolverInterface
            }
         }
      }
-      List<String> breaks = activeBreakGlass().stream().map(row -> row.getValueString("id")).sorted().toList();
-      String payload = JsonUtils.toJson(List.of(userId(), relevant, runtime.policyVersion(), runtime.classificationVersion(), breaks,
-         Objects.requireNonNullElse(SecuredDataMetadata.channel(session), "")));
+      List<QRecord> activeBreaks = breakGlass.stream().filter(row -> "ACTIVE".equals(row.getValueString("status")))
+         .filter(row -> row.getValueInstant("expires_at") != null && row.getValueInstant("expires_at").isAfter(now)).toList();
+      List<String> breaks = activeBreaks.stream().map(row -> row.getValueString("id")).sorted().toList();
+      Instant validUntil = activeBreaks.stream().map(row -> row.getValueInstant("expires_at")).min(Instant::compareTo).orElse(Instant.MAX);
+      String payload = JsonUtils.toJson(List.of(userId(), relevant, policyVersion, classificationVersion, breaks, channel));
      try
      {
-         return (Base64.getUrlEncoder().withoutPadding().encodeToString(MessageDigest.getInstance("SHA-256").digest(payload.getBytes(StandardCharsets.UTF_8))));
+         String value = Base64.getUrlEncoder().withoutPadding().encodeToString(MessageDigest.getInstance("SHA-256").digest(payload.getBytes(StandardCharsets.UTF_8)));
+         return (new RequestFingerprint(System.identityHashCode(this), session, identityOfPermissions(session), countOfPermissions(session), channel, policyVersion, classificationVersion, validUntil, value));
      }
      catch(java.security.NoSuchAlgorithmException e)
      {
@@ -21,9 +21,21 @@
 package com.kingsrook.qbits.secureddata;


+import java.lang.ref.WeakReference;
+import java.time.Duration;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicLong;
+import com.kingsrook.qbits.secureddata.metadata.SecuredDataTables;
+import com.kingsrook.qbits.secureddata.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.cluster.ClusterBus;
+import com.kingsrook.qqq.backend.core.cluster.ClusterCaches;
+import com.kingsrook.qqq.backend.core.cluster.ClusterEvent;
 import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.QSupplementalInstanceMetaData;

@@ -34,9 +46,33 @@ import com.kingsrook.qqq.backend.core.model.metadata.QSupplementalInstanceMetaDa
 public class SecuredDataRuntime implements QSupplementalInstanceMetaData, AutoCloseable
 {
   public static final String NAME = "securedDataRuntime";
+
+   private static final QLogger LOG = QLogger.getLogger(SecuredDataRuntime.class);
+
+   /////////////////////////////////////////////////////////////////////////////////
+   // the three sets of rule rows a node keeps in memory. A change clears them on  //
+   // this node at once and, through QQQ's cluster bus (ClusterCaches), on every   //
+   // other node. MAX_RULE_AGE is the safety net for a lost event: no node uses    //
+   // rule rows older than that without reading them again.                        //
+   /////////////////////////////////////////////////////////////////////////////////
+   public static final String POLICY_CACHE         = "securedData.policies";
+   public static final String CLASSIFICATION_CACHE = "securedData.classifications";
+   public static final String RETENTION_CACHE      = "securedData.retentionRules";
+
+   public static final Duration MAX_RULE_AGE = Duration.ofSeconds(30);
+
+   static
+   {
+      ClusterCaches.shared(POLICY_CACHE, POLICY_CACHE, () -> clearOnThisNode(POLICY_CACHE), null);
+      ClusterCaches.shared(CLASSIFICATION_CACHE, CLASSIFICATION_CACHE, () -> clearOnThisNode(CLASSIFICATION_CACHE), null);
+      ClusterCaches.shared(RETENTION_CACHE, RETENTION_CACHE, () -> clearOnThisNode(RETENTION_CACHE), null);
+   }
+
   private static final AtomicLong STARTUP_VERSION = new AtomicLong(System.currentTimeMillis());
   private final AtomicLong classificationVersion = new AtomicLong(STARTUP_VERSION.incrementAndGet());
   private final AtomicLong policyVersion = new AtomicLong(STARTUP_VERSION.incrementAndGet());
+   private final AtomicLong retentionVersion = new AtomicLong(STARTUP_VERSION.incrementAndGet());
+   private final transient WeakReference<QInstance> owner;
   private final transient SecuredDataQBitConfig config;
   private final transient SecuredDataResolver resolver;
   private final transient SecuredDataKeySource keys = new SecuredDataKeySource();
@@ -44,6 +80,10 @@ public class SecuredDataRuntime implements QSupplementalInstanceMetaData, AutoCl
   private final transient SecuredDataAnomalies anomalies;
   private transient long cachedClassificationVersion;
   private transient List<com.kingsrook.qqq.backend.core.model.data.QRecord> classificationRows = List.of();
+   private transient long classificationRowsLoadedAt;
+   private transient long cachedRetentionVersion;
+   private transient long retentionRulesLoadedAt;
+   private transient List<QRecord> activeRetentionRules = List.of();



@@ -53,6 +93,7 @@ public class SecuredDataRuntime implements QSupplementalInstanceMetaData, AutoCl
   public SecuredDataRuntime(QInstance instance, SecuredDataQBitConfig config)
   {
      this.config = config;
+      this.owner = new WeakReference<>(instance);
      this.resolver = new SecuredDataResolver(this);
      this.anomalies = new SecuredDataAnomalies(config);
      this.logger = new SecuredDataAccessLogger(instance, this);
@@ -137,6 +178,7 @@ public class SecuredDataRuntime implements QSupplementalInstanceMetaData, AutoCl
   public void invalidateClassifications()
   {
      classificationVersion.incrementAndGet();
+      announce(CLASSIFICATION_CACHE);
   }


@@ -147,6 +189,102 @@ public class SecuredDataRuntime implements QSupplementalInstanceMetaData, AutoCl
   public void invalidatePolicies()
   {
      policyVersion.incrementAndGet();
+      announce(POLICY_CACHE);
+   }
+
+
+
+   /*******************************************************************************
+    ** A retention rule changed: forget the active rules here and on every node.
+    *******************************************************************************/
+   public void invalidateRetentionRules()
+   {
+      retentionVersion.incrementAndGet();
+      announce(RETENTION_CACHE);
+   }
+
+
+
+   /*******************************************************************************
+    ** Version of the retention rules this node holds.
+    *******************************************************************************/
+   public long retentionVersion()
+   {
+      return (retentionVersion.get());
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether rows loaded at this System.nanoTime are too old to use unread.
+    *******************************************************************************/
+   static boolean tooOld(long loadedAtNanos)
+   {
+      return (System.nanoTime() - loadedAtNanos > MAX_RULE_AGE.toNanos());
+   }
+
+
+
+   /*******************************************************************************
+    ** Every active retention rule, read once per version and at most MAX_RULE_AGE
+    ** old. A read that fails throws and leaves nothing in place of the rules:
+    ** callers never see "no rules" because the rules could not be read.
+    *******************************************************************************/
+   public synchronized List<QRecord> activeRetentionRules()
+   {
+      long version = retentionVersion();
+      if(cachedRetentionVersion != version || tooOld(retentionRulesLoadedAt))
+      {
+         long loadedAt = System.nanoTime();
+         activeRetentionRules = List.copyOf(SystemWrites.query(SecuredDataTables.RETENTION_RULE, new QQueryFilter()
+            .withCriteria(new QFilterCriteria("is_active", QCriteriaOperator.EQUALS, true))));
+         cachedRetentionVersion = version;
+         retentionRulesLoadedAt = loadedAt;
+      }
+      return (activeRetentionRules);
+   }
+
+
+
+   /*******************************************************************************
+    ** Tell the other nodes (this node has already moved its version). A failure
+    ** to send is logged: the other nodes then read again within MAX_RULE_AGE.
+    *******************************************************************************/
+   private void announce(String cache)
+   {
+      try
+      {
+         QInstance instance = owner.get();
+         if(instance != null)
+         {
+            ClusterBus.publish(instance, new ClusterEvent(ClusterEvent.TYPE_MEMO_INVALIDATE, cache, null));
+         }
+      }
+      catch(RuntimeException e)
+      {
+         LOG.warn("Could not announce a secured-data rule change; other nodes read again within " + MAX_RULE_AGE.toSeconds() + " seconds", e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A rule change announced on the cluster bus (also by this node): move the
+    ** version of the runtime of the instance the event arrived on.
+    *******************************************************************************/
+   private static void clearOnThisNode(String cache)
+   {
+      SecuredDataRuntime runtime = current();
+      if(runtime == null)
+      {
+         return;
+      }
+      switch(cache)
+      {
+         case POLICY_CACHE -> runtime.policyVersion.incrementAndGet();
+         case CLASSIFICATION_CACHE -> runtime.classificationVersion.incrementAndGet();
+         default -> runtime.retentionVersion.incrementAndGet();
+      }
   }


@@ -157,11 +295,13 @@ public class SecuredDataRuntime implements QSupplementalInstanceMetaData, AutoCl
   synchronized List<com.kingsrook.qqq.backend.core.model.data.QRecord> classificationRows()
   {
      long version = classificationVersion();
-      if(cachedClassificationVersion != version)
+      if(cachedClassificationVersion != version || tooOld(classificationRowsLoadedAt))
      {
+         long loadedAt = System.nanoTime();
         classificationRows = List.copyOf(com.kingsrook.qbits.secureddata.support.SystemWrites.query(
            com.kingsrook.qbits.secureddata.metadata.SecuredDataTables.CLASSIFICATION, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter()));
         cachedClassificationVersion = version;
+         classificationRowsLoadedAt = loadedAt;
      }
      return (classificationRows);
   }
@@ -238,7 +238,8 @@ public class SecuredDataTableCustomizers implements TableCustomizerInterface
      }
      SecuredDataRuntime runtime = SecuredDataRuntime.current();
      Runnable invalidate = SecuredDataTables.CLASSIFICATION.equals(table) ? runtime::invalidateClassifications
-         : SecuredDataTables.POLICY.equals(table) || SecuredDataTables.BREAK_GLASS.equals(table) ? runtime::invalidatePolicies : null;
+         : SecuredDataTables.POLICY.equals(table) || SecuredDataTables.BREAK_GLASS.equals(table) ? runtime::invalidatePolicies
+         : SecuredDataTables.RETENTION_RULE.equals(table) ? runtime::invalidateRetentionRules : null;
      if(invalidate != null)
      {
         QBackendTransaction active = transaction == null ? QContext.getQBackendTransaction() : transaction;
@@ -248,6 +249,10 @@ public class SecuredDataTableCustomizers implements TableCustomizerInterface
         }
         else
         {
+            if(SecuredDataTables.RETENTION_RULE.equals(table))
+            {
+               com.kingsrook.qbits.secureddata.retention.RetentionRules.editedInTransaction();
+            }
            active.addAfterCommitCallback(invalidate);
         }
      }
@@ -58,15 +58,68 @@ public final class RetentionRules
      return (names == null ? List.of() : Arrays.stream(names.split(",", -1)).map(String::trim).toList());
   }

+   ///////////////////////////////////////////////////////////////////////////////
+   // set on a thread that changed a rule inside a transaction: until that       //
+   // transaction ends, the thread reads the rules through it (its own edits),   //
+   // not the rules every other thread shares                                    //
+   ///////////////////////////////////////////////////////////////////////////////
+   private static final ThreadLocal<Boolean> EDITED_IN_TRANSACTION = ThreadLocal.withInitial(() -> false);
+
+
+
   /*******************************************************************************
-    ** Fresh rules in the current transaction; edits take effect without a stale cache.
+    ** The active rules of a table that name this field. Core asks this for every
+    ** field of every audited write and every filter criterion of every query, so
+    ** the active rules are read once (SecuredDataRuntime.activeRetentionRules: per
+    ** change, and at most MAX_RULE_AGE old) instead of once per call. A committed
+    ** change is seen at once on the node that made it and on every node the
+    ** cluster event reaches; a transaction that edits rules reads its own edits.
+    ** A failed read throws: it is never "no rules".
    *******************************************************************************/
   public static List<QRecord> active(String table, String field)
   {
-      return (SystemWrites.query(SecuredDataTables.RETENTION_RULE, new QQueryFilter()
-         .withCriteria(new QFilterCriteria("is_active", QCriteriaOperator.EQUALS, true))
-         .withCriteria(new QFilterCriteria("table_name", QCriteriaOperator.EQUALS, table)))
-         .stream().filter(rule -> fields(rule).contains(field)).toList());
+      SecuredDataRuntime runtime = SecuredDataRuntime.current();
+      List<QRecord> rules;
+      if(runtime == null || readsOwnEdits())
+      {
+         rules = SystemWrites.query(SecuredDataTables.RETENTION_RULE, new QQueryFilter()
+            .withCriteria(new QFilterCriteria("is_active", QCriteriaOperator.EQUALS, true))
+            .withCriteria(new QFilterCriteria("table_name", QCriteriaOperator.EQUALS, table)));
+      }
+      else
+      {
+         rules = runtime.activeRetentionRules();
+      }
+      return (rules.stream().filter(rule -> table != null && table.equals(rule.getValueString("table_name"))).filter(rule -> fields(rule).contains(field)).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** A rule was written on this thread inside a transaction that is still open.
+    *******************************************************************************/
+   public static void editedInTransaction()
+   {
+      EDITED_IN_TRANSACTION.set(true);
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether this thread must read the rules through its open transaction.
+    *******************************************************************************/
+   private static boolean readsOwnEdits()
+   {
+      if(!EDITED_IN_TRANSACTION.get())
+      {
+         return (false);
+      }
+      if(QContext.getQBackendTransaction() == null)
+      {
+         EDITED_IN_TRANSACTION.remove();
+         return (false);
+      }
+      return (true);
   }

   /*******************************************************************************
@@ -22,6 +22,7 @@ package com.kingsrook.qbits.secureddata;


 import java.io.Serializable;
+import java.lang.ref.WeakReference;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.List;
@@ -46,6 +47,7 @@ import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.utils.JsonUtils;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
@@ -359,4 +361,92 @@ class SecuredDataAccessLoggerTest
      {
      }
   }
+
+
+   /*******************************************************************************
+    ** The worker starts while the host is still building its instance. An idle
+    ** tick opens no context, so it never validates (or enriches) an unfinished
+    ** instance on the worker thread, and a failing tick is logged instead of
+    ** cancelling every later tick.
+    *******************************************************************************/
+   @Test
+   void idleTicksNeverValidateAnUnfinishedInstance() throws Exception
+   {
+      setup();
+      SecuredDataRuntime runtime = SecuredDataRuntime.current();
+      QInstance unfinished = SecuredDataTestSupport.base();
+      unfinished.addTable(new QTableMetaData().withName("unfinished").withBackendName("not_registered_yet"));
+      SecuredDataAccessLogger idle = new SecuredDataAccessLogger(unfinished, runtime);
+      try
+      {
+         idle.flush();
+         idle.scheduledFlush();
+         assertThat(unfinished.getHasBeenValidated()).isFalse();
+      }
+      finally
+      {
+         idle.close();
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Neither the worker thread nor the JVM shutdown hook keeps a discarded
+    ** instance alive: a host or test that drops its instance without closing
+    ** the runtime lets it be collected.
+    *******************************************************************************/
+   @Test
+   void aDiscardedInstanceCanBeCollected() throws Exception
+   {
+      close();
+      WeakReference<QInstance> discarded = discardedInstance();
+      long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(10);
+      List<byte[]> pressure = new ArrayList<>();
+      while(discarded.get() != null && System.nanoTime() < deadline)
+      {
+         pressure.add(new byte[1 << 20]);
+         if(pressure.size() > 64)
+         {
+            pressure.clear();
+         }
+         System.gc();
+         Thread.sleep(20);
+      }
+      assertThat(discarded.get()).as("instance still reachable from the access logger").isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** Build, use and drop an instance whose worker ticks every 10 ms.
+    *******************************************************************************/
+   private static WeakReference<QInstance> discardedInstance() throws Exception
+   {
+      QInstance instance = SecuredDataTestSupport.base();
+      instance.addBackend(new com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData().withName("memory")
+         .withBackendType(com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule.class));
+      instance.addTable(person("memory"));
+      new SecuredDataQBitProducer().withQBitConfig(new SecuredDataQBitConfig().withAccessLogFlushIntervalMillis(10)).produce(instance);
+      Thread.sleep(50);
+      QContext.clear();
+      return (new WeakReference<>(instance));
+   }
+
+
+
+   /*******************************************************************************
+    ** Hosts that close the runtime themselves can skip the JVM hook; close
+    ** still drains and stops the worker.
+    *******************************************************************************/
+   @Test
+   void shutdownHookIsOptional() throws Exception
+   {
+      setup(config -> config.withRegisterShutdownHook(false));
+      var logger = SecuredDataRuntime.current().logger();
+      assertThat(logger.isWorkerRunning()).isTrue();
+      logger.onAccess(event(FieldAccessEventType.VIEW, null, null));
+      logger.close();
+      assertThat(logger.isWorkerRunning()).isFalse();
+      assertThat(logs()).hasSize(1);
+   }
 }
@@ -33,6 +33,7 @@ import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QVirtualFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
@@ -326,4 +327,22 @@ class SecuredDataResolverTest
      CLOCK.now = NOW.plusSeconds(10);
      assertThat(resolver.isRevealActive("person", "email", 7)).isFalse();
   }
+
+
+   /*******************************************************************************
+    ** A virtual (computed) field is not in getFields, and getField throws for
+    ** it: it resolves through the table classification instead of failing the
+    ** whole read.
+    *******************************************************************************/
+   @Test
+   void virtualFieldsTakeTheTableClassification() throws Exception
+   {
+      QVirtualFieldMetaData display = new QVirtualFieldMetaData("displayName", QFieldType.STRING);
+      person.withVirtualFields(List.of(display));
+      assertThat(SecuredDataClassifications.effective(person, "displayName")).isNull();
+      assertThat(resolver.resolve(person, display).tier()).isEqualTo(FieldAccessTier.FULL);
+      person.withSupplementalMetaData(new AiTableMetaData().withClassification(DataClassification.PII));
+      assertThat(SecuredDataClassifications.effective(person, "displayName")).isEqualTo(DataClassification.PII);
+      assertThat(resolver.resolve(person, display).tier()).isEqualTo(FieldAccessTier.MASKED);
+   }
 }
@@ -0,0 +1,261 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.secureddata;
+
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import com.kingsrook.qbits.secureddata.metadata.SecuredDataTables;
+import com.kingsrook.qbits.secureddata.permissions.SecuredDataPermissions;
+import com.kingsrook.qbits.secureddata.retention.RetentionRules;
+import com.kingsrook.qbits.secureddata.support.SecuredDataMetadata;
+import com.kingsrook.qqq.backend.core.cluster.ClusterBus;
+import com.kingsrook.qqq.backend.core.cluster.ClusterCaches;
+import com.kingsrook.qqq.backend.core.cluster.ClusterEvent;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static com.kingsrook.qbits.secureddata.SecuredDataTestSupport.close;
+import static com.kingsrook.qbits.secureddata.SecuredDataTestSupport.delete;
+import static com.kingsrook.qbits.secureddata.SecuredDataTestSupport.insert;
+import static com.kingsrook.qbits.secureddata.SecuredDataTestSupport.setup;
+import static com.kingsrook.qbits.secureddata.SecuredDataTestSupport.update;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** The rule rows a node keeps (retention rules, policies, classifications) and
+ ** the access fingerprint of a request: read once, cleared by every change on
+ ** every node, never older than the maximum age, and never an empty answer when
+ ** the rules cannot be read.
+ *******************************************************************************/
+class SecuredDataRuleCachesTest
+{
+   private static final List<String> ANNOUNCED = new ArrayList<>();
+
+   static
+   {
+      ClusterBus.on(ClusterEvent.TYPE_MEMO_INVALIDATE, (instance, event) -> ANNOUNCED.add(event.getName()));
+   }
+
+   QInstance          instance;
+   QTableMetaData     person;
+   SecuredDataRuntime runtime;
+
+
+
+   /*******************************************************************************
+    ** A person table with a date, so a retention rule on it is valid.
+    *******************************************************************************/
+   @BeforeEach
+   void init() throws Exception
+   {
+      instance = setup();
+      person = instance.getTable("person");
+      person.withField(new QFieldMetaData("createDate", QFieldType.DATE_TIME).withBackendName("createDate"));
+      runtime = SecuredDataRuntime.current();
+      MemoryRecordStore.setCollectStatistics(true);
+      MemoryRecordStore.resetStatistics();
+      ANNOUNCED.clear();
+   }
+
+
+
+   /*******************************************************************************
+    ** Cleanup.
+    *******************************************************************************/
+   @AfterEach
+   void cleanup()
+   {
+      MemoryRecordStore.setCollectStatistics(false);
+      close();
+   }
+
+
+
+   /*******************************************************************************
+    ** An active rule on one field of the person table.
+    *******************************************************************************/
+   private static QRecord rule(String field) throws Exception
+   {
+      return (insert(SecuredDataTables.RETENTION_RULE, new QRecord().withValue("name", "30 days: " + field).withValue("table_name", "person")
+         .withValue("field_names", field).withValue("age_field_name", "createDate").withValue("age_days", 30).withValue("action", "NULL_WITH_MARKER")));
+   }
+
+
+
+   /*******************************************************************************
+    ** Queries the in-memory store has run since the last reset.
+    *******************************************************************************/
+   private static int queries()
+   {
+      return (MemoryRecordStore.getStatistics().getOrDefault(MemoryRecordStore.STAT_QUERIES_RAN, 0));
+   }
+
+
+
+   /*******************************************************************************
+    ** Core asks for the rules of a field on every audited field and filter
+    ** criterion: many questions are one read, and every committed change (insert,
+    ** update, delete) is seen by the next question.
+    *******************************************************************************/
+   @Test
+   void activeRetentionRulesAreReadOncePerChange() throws Exception
+   {
+      QRecord notes = rule("notes");
+      assertThat(notes.getErrors()).isNullOrEmpty();
+      MemoryRecordStore.resetStatistics();
+      for(int i = 0; i < 50; i++)
+      {
+         assertThat(RetentionRules.active("person", "notes")).hasSize(1);
+         assertThat(RetentionRules.active("person", "email")).isEmpty();
+         assertThat(RetentionRules.active("anotherTable", "notes")).isEmpty();
+         assertThat(RetentionRules.changedOnly("person", "notes")).isFalse();
+      }
+      assertThat(queries()).isLessThanOrEqualTo(1);
+
+      QRecord ssn = rule("ssn");
+      assertThat(RetentionRules.active("person", "ssn")).hasSize(1);
+
+      update(SecuredDataTables.RETENTION_RULE, new QRecord().withValue("id", notes.getValue("id")).withValue("is_active", false));
+      assertThat(RetentionRules.active("person", "notes")).isEmpty();
+
+      delete(SecuredDataTables.RETENTION_RULE, ssn);
+      assertThat(RetentionRules.active("person", "ssn")).isEmpty();
+      assertThat(ANNOUNCED).contains(SecuredDataRuntime.RETENTION_CACHE);
+   }
+
+
+
+   /*******************************************************************************
+    ** A rule change made on another node arrives as a cluster cache event: each
+    ** of the three kinds of rules is read again here. A change made here is
+    ** announced to the other nodes.
+    *******************************************************************************/
+   @Test
+   void aChangeOnAnyNodeClearsTheRulesOnEveryNode() throws Exception
+   {
+      rule("notes");
+      assertThat(RetentionRules.active("person", "notes")).hasSize(1);
+
+      long retention = runtime.retentionVersion();
+      long policies = runtime.policyVersion();
+      long classifications = runtime.classificationVersion();
+      ClusterCaches.invalidate(SecuredDataRuntime.RETENTION_CACHE);
+      ClusterCaches.invalidate(SecuredDataRuntime.POLICY_CACHE);
+      ClusterCaches.invalidate(SecuredDataRuntime.CLASSIFICATION_CACHE);
+      assertThat(runtime.retentionVersion()).isGreaterThan(retention);
+      assertThat(runtime.policyVersion()).isGreaterThan(policies);
+      assertThat(runtime.classificationVersion()).isGreaterThan(classifications);
+
+      MemoryRecordStore.resetStatistics();
+      assertThat(RetentionRules.active("person", "notes")).hasSize(1);
+      assertThat(queries()).isGreaterThanOrEqualTo(1);
+      MemoryRecordStore.resetStatistics();
+      assertThat(RetentionRules.active("person", "notes")).hasSize(1);
+      assertThat(queries()).isZero();
+
+      ANNOUNCED.clear();
+      runtime.invalidatePolicies();
+      runtime.invalidateClassifications();
+      runtime.invalidateRetentionRules();
+      assertThat(ANNOUNCED).contains(SecuredDataRuntime.POLICY_CACHE, SecuredDataRuntime.CLASSIFICATION_CACHE, SecuredDataRuntime.RETENTION_CACHE);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fail closed: when the rules cannot be read, asking for them throws. The
+    ** rules read before are not used, and the answer is never an empty list.
+    *******************************************************************************/
+   @Test
+   void rulesThatCannotBeReadAreNeverAnEmptyAnswer() throws Exception
+   {
+      rule("notes");
+      assertThat(RetentionRules.active("person", "notes")).hasSize(1);
+
+      QTableMetaData ruleTable = instance.getTables().remove(SecuredDataTables.RETENTION_RULE);
+      try
+      {
+         runtime.invalidateRetentionRules();
+         assertThatThrownBy(() -> RetentionRules.active("person", "notes")).isInstanceOf(RuntimeException.class);
+         assertThatThrownBy(() -> RetentionRules.active("person", "notes")).isInstanceOf(RuntimeException.class);
+      }
+      finally
+      {
+         instance.getTables().put(SecuredDataTables.RETENTION_RULE, ruleTable);
+      }
+      assertThat(RetentionRules.active("person", "notes")).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** The safety net for a lost cluster event: rows are read again once they are
+    ** older than the maximum age.
+    *******************************************************************************/
+   @Test
+   void ruleRowsAreNotUsedPastTheirMaximumAge()
+   {
+      assertThat(SecuredDataRuntime.tooOld(System.nanoTime())).isFalse();
+      assertThat(SecuredDataRuntime.tooOld(System.nanoTime() - SecuredDataRuntime.MAX_RULE_AGE.plusSeconds(1).toNanos())).isTrue();
+      assertThat(SecuredDataRuntime.MAX_RULE_AGE.toSeconds()).isLessThanOrEqualTo(60);
+   }
+
+
+
+   /*******************************************************************************
+    ** Core asks for the access fingerprint before every field decision. Within a
+    ** request the same value object is returned; a permission that matters, given
+    ** to the same session object, changes it at once.
+    *******************************************************************************/
+   @Test
+   void theAccessFingerprintIsKeptForTheRequestAndTracksThePermissions()
+   {
+      SecuredDataResolver resolver = runtime.resolver();
+      QSession            session  = QContext.getQSession();
+      String              first    = resolver.getAccessFingerprint();
+      for(int i = 0; i < 20; i++)
+      {
+         assertThat(resolver.getAccessFingerprint()).isSameAs(first);
+      }
+
+      session.getPermissions().add("unrelated.permission");
+      assertThat(resolver.getAccessFingerprint()).isEqualTo(first);
+
+      session.getPermissions().add(SecuredDataMetadata.permissionBase(person) + "." + SecuredDataPermissions.FULL);
+      String granted = resolver.getAccessFingerprint();
+      assertThat(granted).isNotEqualTo(first);
+
+      session.setPermissions(new HashSet<>(List.of("person.read")));
+      assertThat(resolver.getAccessFingerprint()).isNotEqualTo(granted);
+   }
+}