docs: the export policy also needs s3:PutObjectRetention

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs: WORM audit design spec
2026-10-13 19:23:33 -05:00 · 2026-10-13 19:20:29 -05:00 · 2026-10-13 19:17:03 -05:00 · 2026-10-13 19:14:17 -05:00 · 2026-10-13 19:12:10 -05:00 · 2026-01-10 21:05:39 -06:00
35 changed files with 1931 additions and 425 deletions
@@ -1,14 +1,65 @@
 version: 2.1
-setup: true
+
 orbs:
-  qqq-orb: kingsrook/qqq-orb@0.8
+  qqq-orb: kingsrook/qqq-orb@0.6.8
+
+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
+
 workflows:
-  setup:
+
+  test_only:
    jobs:
-    - qqq-orb/generate_pipeline:
-        orb_version: '0.8'
-        filters:
-          branches:
-            ignore: automation/qbit-rc-pending
-          tags:
-            ignore: /.*/
+      - 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+$/ ]
@@ -0,0 +1,20 @@
+# QRun-IO qbit .editorconfig: the Kingsrook layout (3-space indentation, never tabs).
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 3
+tab_width = 3
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{cmd,bat}]
+end_of_line = crlf
@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.cmd text eol=crlf
+mvnw text eol=lf
@@ -1,25 +0,0 @@
-# Standard QRun release caller (v2, thin contract): every push and manual dispatch delegates to the protected qrun-release-v1 channel. Do not edit per repository.
-name: qrun-release
-on:
-  push: {}
-  workflow_dispatch: {}
-permissions:
-  contents: read
-  actions: read
-jobs:
-  release:
-    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/java-docker.yaml@qrun-release-v1
-    with:
-      runner: linux-small
-      docker-runner: container-build
-      browsers: true
-      browser-runner: browser-build
-  postpublish:
-    if: ${{ needs.release.outputs.capture == 'true' }}
-    needs: release
-    permissions:
-      contents: write
-      actions: write
-    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/qrun-source-version.yaml@qrun-release-v1
-    with:
-      runner: linux-small
@@ -0,0 +1,25 @@
+# Weekly, grouped dependency updates. Minor and patch updates arrive as one PR per ecosystem;
+# major updates stay separate so each gets its own review. At most three version-update PRs per
+# ecosystem are open at once. Security updates are enabled in the repository settings and are
+# not limited by this schedule.
+version: 2
+updates:
+  - package-ecosystem: maven
+    directory: /
+    target-branch: develop
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 3
+    groups:
+      maven-minor-and-patch:
+        update-types: [minor, patch]
+
+  - package-ecosystem: github-actions
+    directory: /
+    target-branch: develop
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 3
+    groups:
+      github-actions:
+        update-types: [minor, patch]
@@ -0,0 +1,31 @@
+# GitHub Release Configuration
+# Auto-generates release notes from PR labels
+
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+      - duplicate
+      - invalid
+    authors:
+      - dependabot
+      - dependabot[bot]
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking-change
+        - breaking
+    - title: New Features
+      labels:
+        - enhancement
+        - feature
+    - title: Bug Fixes
+      labels:
+        - bug
+        - fix
+    - title: Dependencies
+      labels:
+        - dependencies
+    - title: Other Changes
+      labels:
+        - "*"
@@ -1,23 +0,0 @@
-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
@@ -0,0 +1,25 @@
+# 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:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Print the plan without merging or creating branches
+        type: boolean
+        default: false
+  pull_request:
+    types: [closed]
+    branches: [develop]
+
+permissions:
+  contents: write
+
+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
+    with:
+      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
@@ -1,20 +1,21 @@
-# Maven
 target/
+.env
+.idea
+*.iml
+*.class
+*.log
 *.jar
 *.war
+*.nar
 *.ear
-
-# IDE
-.idea/
-*.iml
-.vscode/
-.project
-.classpath
-.settings/
-
-# OS
+*.zip
+*.tar.gz
+*.rar
+hs_err_pid*
 .DS_Store
-Thumbs.db
-
-# Logs
-*.log
+*.sw*
+.flattened-pom.xml
+dependency-reduced-pom.xml
+/.env.local
+/.cache/
+.claude/settings.local.json
@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
@@ -1,15 +0,0 @@
-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: none
-test_branch_policy: all
-publish:
-  snapshot: false
-  release_candidate: false
-  release: false
-  asciidoc: false
@@ -0,0 +1,39 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository.
+
+## Overview
+
+QBit WORM Audit makes QQQ audit records write-once: database-enforced append-only audit tables (Postgres triggers plus an INSERT/SELECT-only app role), a hash chain over every audit row with signed checkpoints, a verification action and daily job, and sealed JSONL exports to an S3 Object Lock (COMPLIANCE) bucket through qbit-object-storage. Design: `docs/DESIGN.md`.
+
+## Build commands
+
+```bash
+./mvnw compile
+./mvnw test
+./mvnw verify  # Checkstyle; JaCoCo: 70% instructions, 90% classes
+```
+
+Use the Maven 3.9.11 wrapper (Java 21); Maven 3.10 cannot read the parent POM. On Windows use `./mvnw.cmd`.
+
+## Architecture
+
+Package: `com.kingsrook.qbits.wormaudit`. Entry point: `WormAuditQBitProducer implements QBitMetaDataProducer<WormAuditQBitConfig>`. Config exposes `tableMetaDataCustomizer` and `retentionYears` (default 6).
+
+## Invariants and naming
+
+- Audit rows are never updated or deleted by the application; the only removal path is the audited retention purge through a separate database role, after the retention date.
+- The chain and the sealed exports hash exactly what core wrote. Never add raw PHI to chain rows, checkpoints, exports, logs or alerts.
+- Tables use lowercase snake_case with the `worm_audit_` prefix; backend names equal table names. Permissions use the full `worm_audit` prefix. Processes are table or record actions, never navigation entries.
+
+## Code style
+
+3-space indent, next-line braces, `return (x);`, flower-box Javadoc on classes and methods, fluent `withX()` setters. Follow `checkstyle/` and `CODE_STYLE.md`.
+
+## Dependencies
+
+Parent: `com.kingsrook:qbit-build-parent:2.0.0`. QQQ BOM: `4.1.0-RC.5` (default-active `qqq-snapshot` profile).
+
+## Release flow
+
+CircleCI uses `kingsrook/qqq-orb@0.6.8`: develop publishes SNAPSHOTs, release/* publishes RCs, and only `vX.Y.Z` GA tags publish releases. Hotfix branches run tests only; never push `hotfix/*` or `release/*` by hand. RC automation uses workflow_dispatch or a merged develop PR labelled `release:rc`. Feature branches start from develop and return by PR. Never publish manually.
@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes are documented here, following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffold
@@ -1,15 +1,39 @@
-# qbit-worm-audit
+# CLAUDE.md

-## Knowledge base
+Guidance for coding agents working in this repository.

-Reviewed knowledge for this repo and the wider QQQ platform lives in the second-brain vault:
+## Overview

- Platform hub: `R:/Git.Local/KofTwentyTwo/second-brain/knowledge/qqq/qqq-hub.md`
- This repo's dossier: `R:/Git.Local/KofTwentyTwo/second-brain/knowledge/qqq/repos/qbit-worm-audit.md`
-  (reviewed at commit `294cd30f2d91`, branch `main`, 2026-07-04)
+QBit WORM Audit makes QQQ audit records write-once: database-enforced append-only audit tables (Postgres triggers plus an INSERT/SELECT-only app role), a hash chain over every audit row with signed checkpoints, a verification action and daily job, and sealed JSONL exports to an S3 Object Lock (COMPLIANCE) bucket through qbit-object-storage. Design: `docs/DESIGN.md`.

-Key facts from the review: this repo is an **un-customized instantiation** of the
-`qbit-template-extension` GitHub template — no WORM-audit code exists yet; Maven coordinates are
-still `com.kingsrook.qbits:qbit-example-extension`; qqq pin is pre-4.0 (`qqq-backend-core 0.35.0`
-on main, `0.40.0-SNAPSHOT` on develop); README's "AGPL-3.0" line contradicts the Apache-2.0
-LICENSE. See the dossier's "v4.0 impact" section before starting implementation work here.
+## Build commands
+
+```bash
+./mvnw compile
+./mvnw test
+./mvnw verify  # Checkstyle; JaCoCo: 70% instructions, 90% classes
+```
+
+Use the Maven 3.9.11 wrapper (Java 21); Maven 3.10 cannot read the parent POM. On Windows use `./mvnw.cmd`.
+
+## Architecture
+
+Package: `com.kingsrook.qbits.wormaudit`. Entry point: `WormAuditQBitProducer implements QBitMetaDataProducer<WormAuditQBitConfig>`. Config exposes `tableMetaDataCustomizer` and `retentionYears` (default 6).
+
+## Invariants and naming
+
+- Audit rows are never updated or deleted by the application; the only removal path is the audited retention purge through a separate database role, after the retention date.
+- The chain and the sealed exports hash exactly what core wrote. Never add raw PHI to chain rows, checkpoints, exports, logs or alerts.
+- Tables use lowercase snake_case with the `worm_audit_` prefix; backend names equal table names. Permissions use the full `worm_audit` prefix. Processes are table or record actions, never navigation entries.
+
+## Code style
+
+3-space indent, next-line braces, `return (x);`, flower-box Javadoc on classes and methods, fluent `withX()` setters. Follow `checkstyle/` and `CODE_STYLE.md`.
+
+## Dependencies
+
+Parent: `com.kingsrook:qbit-build-parent:2.0.0`. QQQ BOM: `4.1.0-RC.5` (default-active `qqq-snapshot` profile).
+
+## Release flow
+
+CircleCI uses `kingsrook/qqq-orb@0.6.8`: develop publishes SNAPSHOTs, release/* publishes RCs, and only `vX.Y.Z` GA tags publish releases. Hotfix branches run tests only; never push `hotfix/*` or `release/*` by hand. RC automation uses workflow_dispatch or a merged develop PR labelled `release:rc`. Feature branches start from develop and return by PR. Never publish manually.
@@ -0,0 +1,3 @@
+# Code of Conduct
+
+See Project level [Code of Conduct](https://github.com/QRun-IO/qqq/blob/develop/CODE_OF_CONDUCT.md)
@@ -0,0 +1,3 @@
+# Code Style Guide
+
+* See Project [Code Style Guide](https://github.com/QRun-IO/qqq/blob/develop/CODE_STYLE.md)
@@ -0,0 +1,6 @@
+# Contributing to QBit Secured Data
+
+* See Project [Contributing](https://github.com/QRun-IO/qqq/blob/develop/CONTRIBUTING.md)
+* Branches follow GitFlow: `feature/*` from `develop`, pull requests to `develop`, `release/*` for release candidates, `vX.Y.Z` tags for releases.
+* Commits are signed and follow Conventional Commits.
+* Build and test locally with `./mvnw verify` (Java 21).
@@ -176,7 +176,7 @@

   END OF TERMS AND CONDITIONS

-   Copyright 2022-2025 QRunIO, LLC
+   Copyright 2024 Kingsrook, LLC

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
@@ -1,6 +1,6 @@
-qBit Template - Extension
-Copyright 2022-2025 QRunIO, LLC
+QBit WORM Audit
+Copyright 2026 Kingsrook, LLC

-This product includes software developed at QRunIO, LLC (https://qrun.io/).
+This product includes software developed at Kingsrook, LLC (https://kingsrook.com/).

 Licensed under the Apache License, Version 2.0.
@@ -1,48 +1,49 @@
-# QBit Template: Extension
+# QBit WORM Audit

-Template repository for creating QQQ Extension QBits - infrastructure extensions, customizers, and action handlers.
+Write-once, read-many (WORM) audit for QQQ applications. The QQQ core audit tables (`audit`, `audit_detail`) and this qbit's own tables become append-only at the database level, every audit row is linked into a hash chain with periodic signed checkpoints, a verification action and a daily job detect tampering, and new audit rows are sealed into an S3 bucket with Object Lock in COMPLIANCE mode (default retention 6 years, the HIPAA audit-record retention). Audit content is hashed and sealed exactly as core writes it; with qbit-secured-data, PHI field values in audit details are already HMACs, so no raw PHI reaches the chain or the sealed copies. This repository currently contains the compiling scaffold; the design is in [docs/DESIGN.md](docs/DESIGN.md) once the spec PR lands.

-## What is an Extension QBit?
+## Requirements

-Extension QBits extend or enhance how QQQ operates at the infrastructure/framework level. They provide:
- New backend implementations
- Authentication mechanisms
- Audit capabilities
- Table customizers
- Action handlers
+Java 21 and QQQ 4.1.0-RC.5 or later. PostgreSQL is the supported database for the append-only enforcement. The Maven wrapper pins Maven 3.9.11.

-## Quick Start
+## Install

-1. Click "Use this template" to create your QBit
-2. Run `scripts/customize_template.py` to rename the example
-3. Implement your extension logic
-4. Add tests
-5. Publish to Maven repository
-
-## Structure
-
-```
-src/main/java/com/kingsrook/qbits/example/
-├── ExampleExtensionQBitConfig.java    # Configuration
-├── ExampleExtensionQBitProducer.java  # Entry point
-├── customizers/
-│   └── ExampleTableCustomizer.java    # Table customization
-└── actions/
-    └── ExampleActionCustomizer.java   # Action handling
+```xml
+<dependency>
+   <groupId>com.kingsrook.qbits</groupId>
+   <artifactId>qbit-worm-audit</artifactId>
+   <version>0.1.0-SNAPSHOT</version>
+</dependency>
 ```

-## Key Characteristics
+## Tables and permissions

- **No QAppSection** - Pure infrastructure
- **No user-facing tables** (or minimal operational)
- **Wraps existing tables/processes** with new behavior
- **Validates dependencies** on other QQQ components
+Planned tables (none are produced yet): `worm_audit_chain`, `worm_audit_checkpoint`, `worm_audit_export`, `worm_audit_verification`, `worm_audit_purge`. Backend names match table names. Permissions use the full `worm_audit` prefix.

-## Documentation
+## Configuration

- [Getting Started](docs/00-getting-started.md)
- [Extension Patterns](docs/01-extension-patterns.md)
+`WormAuditQBitConfig` exposes an optional `tableMetaDataCustomizer` and `retentionYears` (default 6).
+
+## Adopting in another app
+
+```java
+new WormAuditQBitProducer()
+   .withQBitConfig(new WormAuditQBitConfig())
+   .produce(qInstance);
+```
+
+Production currently registers the QBit identity and config only. Database changesets, the object-storage bucket and the alert wiring are documented with each phase.
+
+## Build
+
+```bash
+./mvnw compile
+./mvnw test
+./mvnw verify
+```
+
+Verification includes Checkstyle and JaCoCo gates of 70% instructions and 90% classes. On Windows, use `./mvnw.cmd`.

 ## License

-AGPL-3.0 - See [LICENSE](LICENSE)
+[Apache License 2.0](LICENSE). Copyright Kingsrook, LLC.
@@ -0,0 +1,4 @@
+# Security Policy
+
+* See Project [Security Policy](https://github.com/QRun-IO/qqq/blob/develop/SECURITY.md)
+* Report suspected vulnerabilities privately through GitHub private vulnerability reporting on this repository, never in a public issue.
@@ -0,0 +1,246 @@
+<?xml version="1.0"?>
+<!--
+  ~ QQQ - Low-code Application Framework for Engineers.
+  ~ Copyright (C) 2021-2022.  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.
+  -->
+
+<!DOCTYPE module PUBLIC
+        "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
+        "http://checkstyle.sourceforge.net/dtds/configuration_1_3.dtd">
+<!--
+   See reference at https://checkstyle.sourceforge.io/checks.html
+-->
+<module name = "Checker">
+   <property name="charset" value="UTF-8"/>
+
+   <property name="severity" value="warning"/>
+
+   <property name="fileExtensions" value="java, properties, xml"/>
+   <!-- Checks for whitespace                        -->
+   <!-- See http://checkstyle.sf.net/config_whitespace.html -->
+   <module name="FileTabCharacter">
+      <property name="eachLine" value="true"/>
+   </module>
+
+   <!--
+   <module name="LineLength">
+      <property name="max" value="100"/>
+      <property name="ignorePattern" value="^package.*|^import.*|a href|href|http://|https://|ftp://"/>
+   </module>
+   -->
+
+   <module name="TreeWalker">
+      <module name="SuppressWarningsHolder"/>
+      <module name="OuterTypeFilename"/>
+      <module name="IllegalTokenText">
+         <property name="tokens" value="STRING_LITERAL, CHAR_LITERAL"/>
+         <property name="format" value="\\u00(09|0(a|A)|0(c|C)|0(d|D)|22|27|5(C|c))|\\(0(10|11|12|14|15|42|47)|134)"/>
+         <property name="message" value="Consider using special escape sequence instead of octal value or Unicode escaped value."/>
+      </module>
+      <module name="AvoidEscapedUnicodeCharacters">
+         <property name="allowEscapesForControlCharacters" value="true"/>
+         <property name="allowByTailComment" value="true"/>
+         <property name="allowNonPrintableEscapes" value="true"/>
+      </module>
+      <module name="AvoidStarImport"/>
+      <module name="OneTopLevelClass"/>
+      <module name="NoLineWrap"/>
+      <module name="EmptyBlock">
+         <property name="option" value="TEXT"/>
+         <property name="tokens" value="LITERAL_TRY, LITERAL_FINALLY, LITERAL_IF, LITERAL_ELSE, LITERAL_SWITCH"/>
+      </module>
+      <module name="NeedBraces"/>
+      <module name="LeftCurly">
+         <property name="option" value="nl"/>
+      </module>
+      <module name="RightCurly">
+         <property name="option" value="alone"/>
+      </module>
+      <!--
+      <module name="WhitespaceAround">
+         <property name="allowEmptyConstructors" value="true"/>
+         <property name="allowEmptyMethods" value="true"/>
+         <property name="allowEmptyTypes" value="true"/>
+         <property name="allowEmptyLoops" value="true"/>
+         <message key="ws.notFollowed"
+          value="WhitespaceAround: ''{0}'' is not followed by whitespace. Empty blocks may only be represented as '{}' when not part of a multi-block statement (4.1.3)"/>
+          <message key="ws.notPreceded"
+          value="WhitespaceAround: ''{0}'' is not preceded with whitespace."/>
+      </module>
+      -->
+      <module name="OneStatementPerLine"/>
+      <module name="MultipleVariableDeclarations"/>
+      <module name="ArrayTypeStyle"/>
+      <module name="MissingSwitchDefault"/>
+      <module name="FallThrough"/>
+      <module name="UpperEll"/>
+      <module name="ModifierOrder"/>
+      <module name="EmptyLineSeparator">
+         <property name="allowNoEmptyLineBetweenFields" value="true"/>
+      </module>
+      <module name="SeparatorWrap">
+         <property name="id" value="SeparatorWrapDot"/>
+         <property name="tokens" value="DOT"/>
+         <property name="option" value="nl"/>
+      </module>
+      <module name="SeparatorWrap">
+         <property name="id" value="SeparatorWrapComma"/>
+         <property name="tokens" value="COMMA"/>
+         <property name="option" value="EOL"/>
+      </module>
+      <module name="SeparatorWrap">
+         <!-- ELLIPSIS is EOL until https://github.com/google/styleguide/issues/258 -->
+         <property name="id" value="SeparatorWrapEllipsis"/>
+         <property name="tokens" value="ELLIPSIS"/>
+         <property name="option" value="EOL"/>
+      </module>
+      <module name="SeparatorWrap">
+         <!-- ARRAY_DECLARATOR is EOL until https://github.com/google/styleguide/issues/259 -->
+         <property name="id" value="SeparatorWrapArrayDeclarator"/>
+         <property name="tokens" value="ARRAY_DECLARATOR"/>
+         <property name="option" value="EOL"/>
+      </module>
+      <module name="SeparatorWrap">
+         <property name="id" value="SeparatorWrapMethodRef"/>
+         <property name="tokens" value="METHOD_REF"/>
+         <property name="option" value="nl"/>
+      </module>
+      <module name="PackageName">
+         <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
+         <message key="name.invalidPattern"
+          value="Package name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="TypeName">
+         <message key="name.invalidPattern"
+          value="Type name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="MemberName">
+         <property name="format" value="^[_a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
+         <message key="name.invalidPattern" value="Member name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="ParameterName">
+         <property name="format" value="^[a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
+         <message key="name.invalidPattern" value="Parameter name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="CatchParameterName">
+         <property name="format" value="^[a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
+         <message key="name.invalidPattern" value="Catch parameter name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="LocalVariableName">
+         <property name="tokens" value="VARIABLE_DEF"/>
+         <property name="format" value="^[a-zA-Z]([a-z0-9A-Z][a-zA-Z0-9]*)?$"/>
+         <message key="name.invalidPattern" value="Local variable name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="ClassTypeParameterName">
+         <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][_A-Z0-9]*$)"/>
+         <message key="name.invalidPattern" value="Class type name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="MethodTypeParameterName">
+         <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][_A-Z0-9]*$)"/>
+         <message key="name.invalidPattern" value="Method type name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="InterfaceTypeParameterName">
+         <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][_A-Z0-9]*$)"/>
+         <message key="name.invalidPattern" value="Interface type name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="NoFinalizer"/>
+      <module name="GenericWhitespace">
+         <message key="ws.followed" value="GenericWhitespace ''{0}'' is followed by whitespace."/>
+         <message key="ws.preceded" value="GenericWhitespace ''{0}'' is preceded with whitespace."/>
+         <message key="ws.illegalFollow" value="GenericWhitespace ''{0}'' should followed by whitespace."/>
+         <message key="ws.notPreceded" value="GenericWhitespace ''{0}'' is not preceded with whitespace."/>
+      </module>
+      <module name="Indentation">
+         <property name="basicOffset" value="3"/>
+         <property name="braceAdjustment" value="0"/>
+         <property name="caseIndent" value="3"/>
+         <property name="throwsIndent" value="6"/>
+         <property name="lineWrappingIndentation" value="3"/>
+         <property name="arrayInitIndent" value="6"/>
+      </module>
+      <!--
+      <module name="AbbreviationAsWordInName">
+         <property name="ignoreFinal" value="false"/>
+         <property name="allowedAbbreviationLength" value="1"/>
+      </module>
+      <module name="OverloadMethodsDeclarationOrder"/>
+      <module name="VariableDeclarationUsageDistance"/>
+      <module name="CustomImportOrder">
+         <property name="sortImportsInGroupAlphabetically" value="true"/>
+         <property name="separateLineBetweenGroups" value="true"/>
+         <property name="customImportOrderRules" value="STATIC###THIRD_PARTY_PACKAGE"/>
+      </module>
+      -->
+      <module name="CustomImportOrder">
+         <property name="customImportOrderRules" value="SPECIAL_IMPORTS###STANDARD_JAVA_PACKAGE###THIRD_PARTY_PACKAGE###STATIC"/>
+         <property name="specialImportsRegExp" value="^javax\."/>
+         <property name="standardPackageRegExp" value="^java\."/>
+         <property name="sortImportsInGroupAlphabetically" value="true"/>
+         <property name="separateLineBetweenGroups" value="false"/>
+      </module>
+      <module name="MethodParamPad"/>
+      <module name="NoWhitespaceBefore">
+         <property name="tokens" value="COMMA, SEMI, POST_INC, POST_DEC, DOT, ELLIPSIS, METHOD_REF"/>
+         <property name="allowLineBreaks" value="true"/>
+      </module>
+      <module name="ParenPad"/>
+      <module name="OperatorWrap">
+         <property name="option" value="NL"/>
+         <property name="tokens" value="BAND, BOR, BSR, BXOR, DIV, EQUAL, GE, GT, LAND, LE, LITERAL_INSTANCEOF, LOR, LT, MINUS, MOD, NOT_EQUAL, PLUS, QUESTION, SL, SR, STAR, METHOD_REF "/>
+      </module>
+      <module name="AnnotationLocation">
+         <property name="id" value="AnnotationLocationMostCases"/>
+         <property name="tokens" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF"/>
+      </module>
+      <module name="AnnotationLocation">
+         <property name="id" value="AnnotationLocationVariables"/>
+         <property name="tokens" value="VARIABLE_DEF"/>
+         <property name="allowSamelineMultipleAnnotations" value="true"/>
+      </module>
+      <module name="JavadocMethod">
+         <property name="allowMissingParamTags" value="true"/>
+         <property name="allowMissingReturnTag" value="true"/>
+         <property name="allowedAnnotations" value="Override, Test"/>
+      </module>
+      <module name="MissingJavadocMethod">
+         <property name="scope" value="private"/>
+      </module>
+      <module name="MissingJavadocType">
+         <property name="scope" value="private"/>
+      </module>
+      <module name="MethodName">
+         <property name="format" value="^[a-z][a-zA-Z0-9_]*$"/>
+         <message key="name.invalidPattern"
+          value="Method name ''{0}'' must match pattern ''{1}''."/>
+      </module>
+      <module name="EmptyCatchBlock">
+         <property name="exceptionVariableName" value="expected"/>
+      </module>
+      <module name="CommentsIndentation"/>
+
+      <!-- this would be nice, but requires the the @inheritDoc javadoc tag... -->
+      <module name="MissingOverride"/>
+
+   </module>
+   <module name="Header">
+     <property name="headerFile" value="checkstyle/license.txt"/>
+     <property name="fileExtensions" value="java"/>
+     <property name="ignoreLines" value="3"/>
+   </module>
+   <module name="SuppressWarningsFilter"/>
+</module>
@@ -0,0 +1,19 @@
+/*
+ * 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.
+ */
@@ -1,42 +0,0 @@
-# Getting Started
-
-## Prerequisites
-
- Java 17+
- Maven 3.8+
- QQQ 0.23.0+
-
-## Creating Your Extension QBit
-
-1. Click "Use this template" on GitHub
-2. Clone your new repository
-3. Run the customization script:
-   ```bash
-   python scripts/customize_template.py
-   ```
-4. Enter your QBit name when prompted
-
-## Project Structure
-
-```
-src/main/java/com/kingsrook/qbits/yourextension/
-├── YourExtensionQBitConfig.java
-├── YourExtensionQBitProducer.java
-├── customizers/
-└── actions/
-```
-
-## Using Your QBit
-
-```java
-new YourExtensionQBitProducer()
-   .withConfig(new YourExtensionQBitConfig()
-      .withTargetTableName("order"))
-   .produce(qInstance, "myExtension");
-```
-
-## Next Steps
-
- Read [Extension Patterns](01-extension-patterns.md)
- Implement your customization logic
- Add tests
@@ -1,58 +0,0 @@
-# Extension Patterns
-
-## Table Customizers
-
-Add behavior to existing tables:
-
-```java
-public class AuditTableCustomizer
-{
-   public void customize(QTableMetaData table)
-   {
-      table.withField(new QFieldMetaData("createdAt", QFieldType.DATE_TIME));
-      table.withField(new QFieldMetaData("modifiedAt", QFieldType.DATE_TIME));
-
-      table.withCustomizer(
-         TableCustomizers.PRE_INSERT_RECORD,
-         new QCodeReference(AuditPreInsert.class));
-   }
-}
-```
-
-## Action Customizers
-
-Wrap actions with additional behavior:
-
-```java
-public class LoggingActionWrapper implements PreInsertRecordInterface
-{
-   @Override
-   public void preInsertRecord(InsertInput input, QRecord record) throws QException
-   {
-      LOG.info("Inserting record", logPair("table", input.getTableName()));
-   }
-}
-```
-
-## Config Validation
-
-Validate that required components exist:
-
-```java
-@Override
-public void validate(QInstance qInstance, List<String> errors)
-{
-   if(qInstance.getTable(targetTableName) == null)
-   {
-      errors.add("Target table required: " + targetTableName);
-   }
-}
-```
-
-## When to Use Extension QBits
-
- Adding audit logging to tables
- Implementing authentication/authorization
- Adding encryption to fields
- Custom validation rules
- Performance monitoring
@@ -0,0 +1,383 @@
+# QBit WORM Audit: design
+
+Status: approved. **Owner decisions (2026-10-12): all recommendations accepted.** Every open
+question in section 12 is decided as recommended.
+
+## 1. Owner request
+
+> "we also need to ensure that our auditing qbit supports WORM audits as well. and the phi/secure
+> data qbit needs to ensure that we don't leak phi into audits"
+
+Context: HIPAA §164.312(b) audit controls, §164.312(c)(1) integrity, §164.316(b)(2)(i) six-year
+retention of required documentation (audit records are kept to the same horizon), and a
+HITRUST-style review that asks three things: (1) can anyone change or delete an audit record,
+(2) would we know if they did, and (3) is there a copy nobody can alter?
+
+## 2. Goals and non-goals
+
+Goals:
+1. **Append-only at the database level.** No application path, and no ordinary database login,
+   can UPDATE, DELETE or TRUNCATE audit rows. The only removal is an audited retention purge,
+   after the retention date, through a separate database role.
+2. **Tamper evidence.** Every audit row is linked into a hash chain. Signed checkpoints anchor the
+   chain. A verification action and a daily job report the exact first broken row.
+3. **Sealed copies.** New audit rows and checkpoints are exported on a schedule to an S3 bucket
+   with Object Lock in COMPLIANCE mode (default six years), and can be verified against the live
+   chain.
+4. **No PHI in the WORM layer.** The chain and the exports seal exactly what core wrote. With
+   qbit-secured-data that means HMACs for classified values, never plaintext.
+
+Non-goals: changing what core audits (that is core's and qbit-secured-data's job); protecting
+against a Postgres superuser *preventing* a change (a superuser can disable triggers; the
+chain, the signatures and the Object Lock copies make that change *detectable*, see 4.5).
+
+## 3. Scope: which tables
+
+| Table (QQQ name / kof22 physical) | Treatment |
+|---|---|
+| `audit` / `audit` | Append-only (UPDATE, DELETE, TRUNCATE rejected). Chained. |
+| `auditDetail` / `audit_detail` | Append-only. Chained with its header. |
+| `auditTable` / `audit_table` | Lookup. DELETE and TRUNCATE rejected; UPDATE of `id` or `name` rejected (label and dates may change). Names are resolved into the chained content, so a later rename is detected. |
+| `auditUser` / `audit_user` | As `audit_table`. |
+| `worm_audit_chain`, `worm_audit_checkpoint`, `worm_audit_export`, `worm_audit_verification`, `worm_audit_purge` | The qbit's own tables: all append-only. |
+
+Physical names come from the host's backend (kof22 maps camelCase to snake_case). The DDL is a
+template rendered for the host's names (section 5.4).
+
+## 4. Append-only enforcement (Postgres first)
+
+### 4.1 Triggers
+One function, `worm_audit_reject()`, attached as:
+- `BEFORE UPDATE OR DELETE ... FOR EACH ROW` on every append-only table;
+- `BEFORE TRUNCATE ... FOR EACH STATEMENT` on every append-only table;
+- on the two lookups, a row trigger that rejects DELETE and any UPDATE that changes `id` or
+  `name`.
+
+The error is explicit and greppable:
+
+```
+ERROR:  worm_audit: audit rows are write-once; UPDATE of "audit" is not allowed (id=4211). Expired rows are removed only by worm_audit_purge().
+SQLSTATE: P0001 (HINT: see qbit-worm-audit docs/DESIGN.md section 4)
+```
+
+In the application the qbit also removes the update and delete capabilities from these tables'
+QQQ metadata, so the admin UI and both APIs never offer edit or delete, and a direct call gets
+QQQ's standard "table does not support update/delete" error before reaching the database. The
+qbit maps a `P0001` with the `worm_audit:` prefix to a `QUserFacingException`: "Audit records are
+write-once and cannot be changed or deleted."
+
+### 4.2 The retention purge (the only removal path)
+`worm_audit_purge(p_cutoff timestamptz)` is a `SECURITY DEFINER` function owned by the schema
+owner. `EXECUTE` is revoked from `PUBLIC` and granted only to the role `worm_audit_purger`, which
+the app role is not a member of.
+
+1. It refuses (and records a `REFUSED` row in `worm_audit_purge`, then returns; no exception, so
+   the record survives) when `p_cutoff > now() - retention`. The retention interval is a constant
+   compiled into the function by the changeset (default `6 years`), so shortening it is a schema
+   migration, reviewed and itself audited.
+2. It purges only a **chain prefix**: the audits whose chain links all lie at or before the last
+   link whose audit timestamp is older than the cutoff, together with their details and links.
+3. It sets a transaction-local flag (`set_config('worm_audit.purging', 'on', true)`). The reject
+   trigger allows DELETE only when that flag is on **and** `current_user` is the function owner
+   **and** the row is older than the retention interval. Setting the flag from another session
+   does nothing, because `current_user` is not the owner.
+4. It writes a `PURGED` row: who (session_user), cutoff, retention, counts, and the **anchor**
+   (the last purged link's id and hash). Verification continues from the anchor.
+
+The purge runs from an ops runbook (`psql` as `worm_audit_purger`). Version 0.1 has no UI action;
+the app home lists purge rows, including refusals.
+
+### 4.3 GRANT model
+
+| Role | Owns | Grants on append-only tables |
+|---|---|---|
+| `<app>_owner` (Liquibase) | tables, functions, triggers | all (owner) |
+| `<app>` (runtime) | nothing | `SELECT, INSERT`; `USAGE` on their sequences. No UPDATE, DELETE or TRUNCATE. |
+| `worm_audit_purger` (ops) | nothing | `EXECUTE worm_audit_purge`; nothing else |
+
+When a host uses one role for both migrations and runtime (kof22 today), the triggers still stop
+every UPDATE, DELETE and TRUNCATE from the application, but the role can `ALTER TABLE ... DISABLE
+TRIGGER`. The docs recommend splitting the roles, and the app home shows a warning when the
+runtime role owns the audit tables (checked through `pg_tables.tableowner = current_user`).
+
+### 4.4 Changesets
+The qbit ships `src/main/resources/com/kingsrook/qbits/wormaudit/ddl/postgres/worm-audit.sql`,
+a Liquibase formatted-SQL template with placeholders for the four core audit table names, the
+app role and the retention interval, plus a renderer (`WormAuditDdl.postgres(config)`) and the
+rendered default (`docs/ddl/worm-audit-postgres.sql`, snake_case names). Hosts copy the rendered
+file into their changelog (kof22: `changesets/features/YYYY-MM-DD-worm-audit.sql`). It creates the
+qbit tables, the functions, the triggers, the purger role (`CREATE ROLE ... NOLOGIN` when it is
+missing) and the grants. It is idempotent (`CREATE OR REPLACE`, `DROP TRIGGER IF EXISTS`).
+
+### 4.5 Threat model summary
+
+| Actor | Can modify audit rows? | Detected by |
+|---|---|---|
+| App user, admin UI, QQQ APIs, assistant | No (capabilities removed; triggers) | n/a |
+| SQL injection or a bug as the runtime role | No (triggers; no grant) | n/a |
+| Owner role (migrations) | Only by disabling triggers | chain verification (daily), alert |
+| Postgres superuser rewriting rows and recomputing the chain | Yes | checkpoint signatures (no signing key in the DB); sealed exports in Object Lock |
+| Anyone deleting the sealed copies | No (COMPLIANCE mode: not even the bucket root, until expiry) | n/a |
+
+### 4.6 Other databases (documented, not shipped in 0.1)
+- **MySQL/MariaDB:** `BEFORE UPDATE`/`BEFORE DELETE` triggers with `SIGNAL SQLSTATE '45000'`;
+  no TRUNCATE trigger, so revoke `DROP` from the app user; purge through a `SQL SECURITY DEFINER`
+  procedure.
+- **SQL Server:** `INSTEAD OF UPDATE, DELETE` triggers plus `DENY UPDATE, DELETE` to the app user.
+- **H2** (tests only): no enforcement; the chain and the exports work on any QQQ RDBMS or memory
+  backend, so tamper *evidence* is database-independent.
+
+## 5. Tamper evidence
+
+### 5.1 Canonical content (agreed with qbit-secured-data)
+One canonical document per audit header: the header plus all of its detail rows, as RFC 8785 JCS
+JSON (sorted keys, no insignificant whitespace, UTF-8):
+
+```json
+{"audit":{"clientChannel":null,"id":4211,"message":"Record was Edited","recordId":"17","table":"cms_page","timestamp":"2026-10-13T21:04:05.123456Z","user":"james"},
+ "details":[{"fieldName":"title","id":9001,"message":"Changed Title from ...","newValue":"...","oldValue":"..."}],
+ "v":1}
+```
+
+- Values are exactly as stored: no formatting, no re-masking, no lookups other than resolving
+  `auditTableId`/`auditUserId` to their names. `details` are sorted by id.
+- With qbit-secured-data's core hook (QRun-IO/qqq#1161, `docs/SECURED-DATA.md` §14.2), PII and
+  PHI values are tokenised inside `DMLAuditAction` before `AuditAction` inserts, in the same
+  transaction as the data change, so the token is the only form ever written. Stored forms (ASCII,
+  at most 200 characters) in `oldValue`/`newValue` are
+  `hmac:v1:<keyId>:<b64url>`, `shred:v1:<auditKeyId>:<b64url>`, `changed:v1`,
+  `wiped:v1:<ruleId>` and `shredded:v1:<ruleId>` (the last is its own detail row, written when
+  keys are destroyed, and is chained like any other row). Detail messages for those fields
+  are replaced with value-free ones ("Changed <Label>"); header messages carry no field values.
+  The canonical form, the chain and the exports therefore contain tokens only, and verifying the
+  chain never needs a key. The WORM layer never reads, joins or exports
+  `secured_data_audit_key` or any other `secured_data_*` table. Crypto-shredding (destroying a
+  record's key) leaves the HMACs and the chain intact; they simply become unlinkable.
+- The canonical JSON is never stored in the database. The chain stores ids and hashes only, so
+  the qbit adds no new copy of audit content to the database.
+
+### 5.2 The chain: a single asynchronous chainer (recommended)
+`link_hash = SHA-256(prev_link_hash || 0x00 || canonical_bytes)`, hex, with the genesis
+`prev_link_hash` = 64 zeros.
+
+Core inserts audits from many threads, and headers and details may be inserted in separate
+autocommit statements (core passes the caller's transaction, which may be null). Computing the
+chain in core's write path would need a global lock on every audited write, and a trigger-based
+chain would need the canonical form in SQL. The design instead uses **one chainer**:
+
+- A scheduled job (every 30 s by default) takes `pg_try_advisory_xact_lock` (any other instance
+  skips that tick; on non-Postgres backends, a single-row lock table with `SELECT ... FOR
+  UPDATE`). It selects audit headers that are **older than a settle horizon** (default 60 s, so
+  their details have been committed) and not yet chained (an anti-join on the unique
+  `worm_audit_chain.audit_id`), in `(timestamp, id)` order. Then it appends links in batches.
+- Link ids are assigned by the chainer as `max(id) + 1` inside the lock, not from a sequence, so
+  the chain is contiguous (a sequence gaps on rollback).
+- **Late arrivals** (a header whose id sorts before already-chained ones because its transaction
+  committed late) are chained when they appear. The chain order is chaining order, not audit id
+  order, and each link records its `audit_id`.
+- **Late details** (a detail inserted after its header was chained) get their own link,
+  `kind = LATE_DETAIL`, covering exactly those detail ids. Verification flags any detail not
+  covered by exactly one link.
+- Unique constraints back the lock: `UNIQUE (audit_id) WHERE kind = 'AUDIT'`, and the detail
+  coverage.
+
+Why not per-partition chains: they make each partition's chain shorter but multiply heads,
+checkpoints and verification state, and they still need a writer per partition. One chainer
+handles thousands of rows a second in batches, which is well above audit volume, and keeps a
+single head to sign. The table carries no partition column (YAGNI). A future partitioned mode
+would add one.
+
+Window: a row is unchained for at most horizon plus interval (about 90 s). During that window the
+triggers still protect it. The chain defends against privileged tampering, which the window does
+not change materially.
+
+### 5.3 Signed checkpoints (`worm_audit_checkpoint`)
+Every hour, and every 10,000 links, the chainer writes a checkpoint for the links since the last
+one: `from_link_id`, `to_link_id`, `head_hash` (the last link hash), `merkle_root` (a binary
+SHA-256 Merkle tree over the range's link hashes, so a single exported range can be proven
+without the whole chain), `key_id`, `public_key`, `algorithm = Ed25519` and `signature` over the
+JCS form of those fields. The signing key comes from config (`WormAuditQBitConfig.signingKey`, a
+supplier; kof22: env `WORM_AUDIT_SIGNING_KEY` from Infisical) and never touches the database. The
+public key is stored on each checkpoint and pinned in config (`trustedPublicKeys`), so a forged
+checkpoint signed with another key fails verification. Rotation adds a new key id. Old
+checkpoints verify against their own pinned key.
+
+### 5.4 Verification
+**"Verify audit chain"**, a table action on `worm_audit_chain` (and on selected links), is a
+standard streamed ETL:
+- Extract: the links in scope (all since the purge anchor, or the selection), in id order.
+- Transform: recompute each link from the live audit rows (`prev` continuity, canonical content,
+  `link_hash`); check checkpoint signatures and Merkle roots; for a full run, check completeness
+  (every settled audit and detail is covered exactly once).
+- Load: one `worm_audit_verification` row.
+- Review: "1,204,331 chain links will be verified (links 1–1,204,331, 121 checkpoints)."
+- Result: "1,204,331 links verified" or, on failure, one line per break, each with the exact row:
+  "Break at link 88,412 (audit 90,117, table cms_page, record 17): content differs from the
+  chained hash" / "audit_detail 9,002 is not covered by the chain" / "checkpoint 41: signature
+  does not verify".
+
+**Daily verification**: a scheduled job runs the same verifier at 03:00. A failure raises
+`QAlerts.raise(new AlertSignal("worm_audit.chain.break").withDedupKey("chain")...)` with the first
+break in the title and the verification record as the record ref; a later pass resolves it. Every
+run sends `QAlerts.heartbeat("worm_audit.verify.daily")`. `QAlerts` is the core producer SPI
+(QQQ 4.1.0-RC.5), so the qbit needs no dependency on qbit-alerts. With no alerts implementation
+installed the alerts go to the log.
+
+## 6. Sealed exports
+
+### 6.1 Export job
+Daily at 02:00 (configurable), and by the table action "Export now" on `worm_audit_export`:
+1. Range: links after the last export's `to_link_id`, up to the latest checkpoint. Exports are
+   contiguous by construction. The app home flags a gap (a range not covered) and lag.
+2. Objects under `<prefix>/<yyyy>/<mm>/<dd>/<from>-<to>/`:
+   - `links.jsonl`: one line per link: `{"link":{id,kind,auditId,detailIds,prevHash,linkHash},"content":<canonical document>}`;
+   - `checkpoints.jsonl`: the checkpoints in range, with signatures;
+   - `manifest.json`: format version, range, counts, the SHA-256 of each file, `head_hash`,
+     the previous export's manifest SHA-256 (the exports form their own chain), qbit version.
+3. Each object is put through qbit-object-storage (`SystemStorage`, bucket alias from config,
+   default `worm_audit`) with `LockMode.COMPLIANCE` and `retainUntil = now + retentionYears`. The
+   export refuses to run, and alerts `worm_audit.export.failed`, when the bucket does not report
+   the `OBJECT_LOCK` capability or the put does not echo the lock.
+4. On success it inserts one `worm_audit_export` row (insert-only; a failed export leaves no row,
+   and its alert carries the reason).
+
+### 6.2 Restore and verify a sealed export
+"Verify sealed export", a record action on `worm_audit_export` (standard ETL), downloads the
+objects. It checks the manifest hashes, the lock mode and retain-until of each object, the link
+hashes recomputed from the exported content, the checkpoint signatures, and the export's link to
+the previous manifest. Then it compares each exported link and content document with the live
+chain and the live audit rows. Result lines name each difference ("link 88,412: live content
+differs from the sealed copy (sealed 2026-10-14)"). This is also the restore tool: the exported
+content is the canonical audit content, so a verified export is evidence of the original rows
+after a live tamper. A purged range stays verifiable from the sealed copy alone. Writing restored
+rows back into a live table is out of scope (it would need the purge role and break append-only).
+
+## 7. Tables
+
+All tables use the host's RDBMS backend, are append-only (section 4), are audited by nothing
+(auditing the audit tables would recurse), have full record screens, and are searchable in Quick
+Search. ESB table events are on for `worm_audit_verification` and `worm_audit_export` (the
+events integrations care about); chain links are high-volume and publish none.
+
+- **`worm_audit_chain`** [Audit Chain Link]: `id` (contiguous), `kind` (AUDIT, LATE_DETAIL),
+  `audit_id`, `detail_ids` (comma list, at most 250 per link), `prev_hash`, `link_hash`,
+  `chained_at`. Unique `(audit_id) where kind = 'AUDIT'`.
+- **`worm_audit_checkpoint`** [Checkpoint]: `id`, `from_link_id`, `to_link_id`, `link_count`,
+  `head_hash`, `merkle_root`, `algorithm`, `key_id`, `public_key`, `signature`, `created_at`.
+- **`worm_audit_export`** [Sealed Export]: `id`, `from_link_id`, `to_link_id`,
+  `from_checkpoint_id`, `to_checkpoint_id`, `bucket_alias`, `object_prefix`, `manifest_key`,
+  `manifest_sha256`, `prev_manifest_sha256`, `object_count`, `byte_count`, `lock_mode`,
+  `retain_until`, `sealed_at`.
+- **`worm_audit_verification`** [Verification]: `id`, `kind` (CHAIN, SEALED_EXPORT), `trigger`
+  (SCHEDULE, USER), `started_at`, `finished_at`, `from_link_id`, `to_link_id`, `links_checked`,
+  `outcome` (PASS, FAIL), `break_count`, `first_break_link_id`, `first_break_audit_id`,
+  `first_break_reason`, `export_id`, `run_by`.
+- **`worm_audit_purge`** [Purge]: `id`, `requested_at`, `requested_by`, `cutoff`,
+  `retention_interval`, `outcome` (PURGED, REFUSED), `reason`, `audits_deleted`,
+  `details_deleted`, `links_deleted`, `anchor_link_id`, `anchor_hash`.
+
+Nav (the app "WORM Audit"): Home, Verifications, Sealed Exports, Checkpoints, Audit Chain, Purges.
+Checkpoints list their links as a child list. Exports and verifications link their checkpoints
+and links.
+
+## 8. Permissions and the assistant wall
+- Table permissions use the full name (`worm_audit_chain.read`, ...). There are no insert, edit or
+  delete permissions to grant: the capabilities are absent.
+- Process permissions: `worm_audit.verify`, `worm_audit.export`. The home is visible with read on
+  any `worm_audit_*` table.
+- The assistant channel is denied `worm_audit_*`. The qbit registers
+  `ClientChannelsMetaData.ofOrWithNew(qInstance).withDeniedPattern("assistant", "worm_audit_*")`
+  (core, QQQ 4.1.0-RC.6, #1141). On RC.5 it does so reflectively when the class is present. A
+  one-line core PR also adds `worm_audit_*` to `ASSISTANT_DEFAULT_DENIED_PATTERNS`, so the wall
+  holds even if the qbit is configured without its producer. Core's `audit*` pattern already
+  covers the core audit tables.
+
+## 9. App home
+A real home that owns the data (no duplicate dashboard), built from standard widgets, served
+through `/qqq/v1/widget` like every QQQ widget:
+- **Chain status**: links chained, last link time, unchained backlog (with the settle horizon),
+  last verification (time, outcome, links), open breaks with the first break's exact row and a
+  link to the verification record.
+- **Export status**: last sealed export (range, time, retain-until), lag in links and hours,
+  gaps, and bucket lock state (COMPLIANCE, retention).
+- **Retention**: configured years, the purge anchor, the oldest live audit, the next eligible
+  purge date.
+- **Recent purges**: the last 10 purge rows, refusals included.
+- **Setup warnings**: triggers missing on any table (checked via `pg_trigger`), runtime role owns
+  the audit tables, signing key or trusted keys missing, bucket without Object Lock.
+
+The home must be readable at every width (390 to 1920 px) in light and dark mode, with no inner
+horizontal scroll. Screenshots go in `docs/screenshots/`. If a custom endpoint is ever needed, it
+registers as a `MiddlewareSpecExtension` under `/qqq/v1/qbit/worm-audit/...`
+(docs/UI-API-EXTENSIONS.md). The design needs none.
+
+## 10. Configuration (`WormAuditQBitConfig`)
+`retentionYears` (6), `signingKey` (supplier of an Ed25519 private key), `trustedPublicKeys`
+(key id to public key), `chainIntervalSeconds` (30), `settleHorizonSeconds` (60),
+`checkpointEveryLinks` (10,000), `checkpointEveryMinutes` (60), `exportBucketAlias` (`worm_audit`),
+`exportPrefix` (`worm-audit`), `exportCron` (02:00 daily), `verifyCron` (03:00 daily),
+`coreAuditTableNames` (physical names, defaulting to QQQ's), `tableMetaDataCustomizer`.
+
+## 11. Tests (acceptance)
+1. **Postgres Testcontainers** (`postgres:16`): the rendered DDL applies twice (idempotent);
+   UPDATE, DELETE and TRUNCATE on `audit`, `audit_detail` and each `worm_audit_*` table fail with
+   the `worm_audit:` message; lookup renames fail and label changes succeed; the runtime role has
+   no UPDATE/DELETE grant; `worm_audit_purge` refuses a recent cutoff (and records it), purges an
+   expired prefix as the purger role, records the anchor, and verification passes from the
+   anchor; setting `worm_audit.purging` from the app session does not allow DELETE.
+2. **Chain**: chain, verify (PASS); a forced tamper (triggers disabled as superuser, one
+   `audit_detail.new_value` changed) is detected, naming that exact link, audit and detail; a
+   deleted row, an inserted row, a reordered link and a forged checkpoint are each detected.
+3. **Concurrency**: 8 threads inserting audits (with late commits and details in separate
+   statements) while 3 chainers run. The chain is contiguous, every audit and detail is covered
+   exactly once, and verification passes.
+4. **Exports (MinIO Testcontainers, bucket with Object Lock)**: export, then verify the round
+   trip; every object has COMPLIANCE retention; deleting or overwriting an object version is
+   refused by MinIO; a tampered live row is reported by "Verify sealed export"; a bucket without
+   Object Lock makes the export refuse and alert.
+5. **PHI**: a field classified PHI (`AiFieldMetaData.withClassification(DataClassification.PHI)`,
+   read through `AiDataClassifications.ofField`) is written with the value `CANARY-PHI-<random>`.
+   With secured-data's audit token hook (a stand-in producing the same `hmac:v1:` form in the
+   qbit's tests until the core hook ships), the audit header, the details (old, new, message),
+   the canonical content and the export JSONL contain neither the canary nor any substring of it
+   longer than 4 characters.
+6. **Alerts**: a break raises `worm_audit.chain.break` through `QAlerts` (captured by a test
+   sink); a later pass resolves it.
+7. Coverage gates: 70% instructions, 90% classes.
+
+## 12. Decisions (all accepted as recommended, 2026-10-12)
+| # | Question | Decision |
+|---|---|---|
+| 1 | Chain construction | A single asynchronous chainer with a settle horizon, contiguous link ids and late-arrival links (5.2), not synchronous or per-partition chains. |
+| 2 | Chain storage | A sidecar table (`worm_audit_chain`), not columns on core tables, so core's schema is untouched and no UPDATE of audit rows is ever needed. |
+| 3 | Checkpoints | Hourly or every 10,000 links; Ed25519; Merkle root per range. |
+| 4 | Lookup tables | DELETE and id/name changes rejected; names resolved into the content. |
+| 5 | Purge | SQL function plus a purger role only, chain-prefix only, no UI action in 0.1. |
+| 6 | Export | Daily JSONL plus manifest, COMPLIANCE, six years, contiguous ranges, the exports form their own chain. |
+| 7 | Databases | Postgres enforced; MySQL and SQL Server documented; evidence on any backend. |
+
+## 13. Phases
+- **(a)** DDL and renderer, capabilities guard, chain and chainer, checkpoints, verification
+  action and daily job with alerts, the assistant deny pattern; tests 1–3, 5 and 6.
+- **(b)** Sealed exports and the export verifier through qbit-object-storage; test 4.
+- **(c)** App home and setup warnings, screenshots; kof22 adoption (draft Website-Backend PR, a
+  feature changeset) and the infra proposal for an Object Lock bucket (section 14).
+
+## 14. Adoption infrastructure (kof22, proposal only)
+- **Bucket:** `kof22-worm-audit` on the kof22 MinIO, created by `minio-bucket-init` with
+  `mc mb --with-lock --ignore-existing` and `mc retention set --default COMPLIANCE 6y`. Object
+  Lock can only be enabled at bucket creation.
+- **Policy:** `kof22-app` gets `s3:PutObject`, `s3:GetObject`, `s3:ListBucket`,
+  `s3:GetObjectRetention`, `s3:PutObjectRetention` (needed to set the lock on each put),
+  `s3:GetBucketObjectLockConfiguration` on that bucket. No delete, and no
+  `s3:BypassGovernanceRetention` (irrelevant under COMPLIANCE anyway).
+- **Off-site:** COMPLIANCE on a single homelab MinIO stops every API deletion, but not someone
+  destroying the volume. Recommend extending `media-offsite-copy` to replicate the bucket to a B2
+  bucket with Object Lock (COMPLIANCE, 6 years).
+- **Secrets:** `WORM_AUDIT_SIGNING_KEY` (Ed25519 PKCS#8, base64) generated in Praetor
+  `terraform/infisical-config` and delivered by ESO. The public key goes in the backend config.
+- **Database:** split the kof22 owner and runtime roles when convenient (4.3). Until then the
+  home shows the owner warning.
+
+These are owner-run (Praetor and cluster-gitops are applied by the owner). The qbit only
+documents them.
@@ -0,0 +1,295 @@
+#!/bin/sh
+# ----------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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
+#
+#    http://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.
+# ----------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------
+# Apache Maven Wrapper startup batch script, version 3.3.4
+#
+# Optional ENV vars
+# -----------------
+#   JAVA_HOME - location of a JDK home dir, required when download maven via java source
+#   MVNW_REPOURL - repo url base for downloading maven distribution
+#   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+#   MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output
+# ----------------------------------------------------------------------------
+
+set -euf
+[ "${MVNW_VERBOSE-}" != debug ] || set -x
+
+# OS specific support.
+native_path() { printf %s\\n "$1"; }
+case "$(uname)" in
+CYGWIN* | MINGW*)
+  [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")"
+  native_path() { cygpath --path --windows "$1"; }
+  ;;
+esac
+
+# set JAVACMD and JAVACCMD
+set_java_home() {
+  # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched
+  if [ -n "${JAVA_HOME-}" ]; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ]; then
+      # IBM's JDK on AIX uses strange locations for the executables
+      JAVACMD="$JAVA_HOME/jre/sh/java"
+      JAVACCMD="$JAVA_HOME/jre/sh/javac"
+    else
+      JAVACMD="$JAVA_HOME/bin/java"
+      JAVACCMD="$JAVA_HOME/bin/javac"
+
+      if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then
+        echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2
+        echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2
+        return 1
+      fi
+    fi
+  else
+    JAVACMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v java
+    )" || :
+    JAVACCMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v javac
+    )" || :
+
+    if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then
+      echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2
+      return 1
+    fi
+  fi
+}
+
+# hash string like Java String::hashCode
+hash_string() {
+  str="${1:-}" h=0
+  while [ -n "$str" ]; do
+    char="${str%"${str#?}"}"
+    h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296))
+    str="${str#?}"
+  done
+  printf %x\\n $h
+}
+
+verbose() { :; }
+[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; }
+
+die() {
+  printf %s\\n "$1" >&2
+  exit 1
+}
+
+trim() {
+  # MWRAPPER-139:
+  #   Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds.
+  #   Needed for removing poorly interpreted newline sequences when running in more
+  #   exotic environments such as mingw bash on Windows.
+  printf "%s" "${1}" | tr -d '[:space:]'
+}
+
+scriptDir="$(dirname "$0")"
+scriptName="$(basename "$0")"
+
+# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties
+while IFS="=" read -r key value; do
+  case "${key-}" in
+  distributionUrl) distributionUrl=$(trim "${value-}") ;;
+  distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;;
+  esac
+done <"$scriptDir/.mvn/wrapper/maven-wrapper.properties"
+[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+
+case "${distributionUrl##*/}" in
+maven-mvnd-*bin.*)
+  MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/
+  case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in
+  *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;;
+  :Darwin*x86_64) distributionPlatform=darwin-amd64 ;;
+  :Darwin*arm64) distributionPlatform=darwin-aarch64 ;;
+  :Linux*x86_64*) distributionPlatform=linux-amd64 ;;
+  *)
+    echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2
+    distributionPlatform=linux-amd64
+    ;;
+  esac
+  distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip"
+  ;;
+maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;;
+*) MVN_CMD="mvn${scriptName#mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;;
+esac
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}"
+distributionUrlName="${distributionUrl##*/}"
+distributionUrlNameMain="${distributionUrlName%.*}"
+distributionUrlNameMain="${distributionUrlNameMain%-bin}"
+MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}"
+MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")"
+
+exec_maven() {
+  unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || :
+  exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD"
+}
+
+if [ -d "$MAVEN_HOME" ]; then
+  verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  exec_maven "$@"
+fi
+
+case "${distributionUrl-}" in
+*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;;
+*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;;
+esac
+
+# prepare tmp dir
+if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then
+  clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; }
+  trap clean HUP INT TERM EXIT
+else
+  die "cannot create temp dir"
+fi
+
+mkdir -p -- "${MAVEN_HOME%/*}"
+
+# Download and Install Apache Maven
+verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+verbose "Downloading from: $distributionUrl"
+verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+# select .zip or .tar.gz
+if ! command -v unzip >/dev/null; then
+  distributionUrl="${distributionUrl%.zip}.tar.gz"
+  distributionUrlName="${distributionUrl##*/}"
+fi
+
+# verbose opt
+__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR=''
+[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v
+
+# normalize http auth
+case "${MVNW_PASSWORD:+has-password}" in
+'') MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+esac
+
+if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then
+  verbose "Found wget ... using wget"
+  wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl"
+elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then
+  verbose "Found curl ... using curl"
+  curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl"
+elif set_java_home; then
+  verbose "Falling back to use Java to download"
+  javaSource="$TMP_DOWNLOAD_DIR/Downloader.java"
+  targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName"
+  cat >"$javaSource" <<-END
+	public class Downloader extends java.net.Authenticator
+	{
+	  protected java.net.PasswordAuthentication getPasswordAuthentication()
+	  {
+	    return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() );
+	  }
+	  public static void main( String[] args ) throws Exception
+	  {
+	    setDefault( new Downloader() );
+	    java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() );
+	  }
+	}
+	END
+  # For Cygwin/MinGW, switch paths to Windows format before running javac and java
+  verbose " - Compiling Downloader.java ..."
+  "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java"
+  verbose " - Running Downloader.java ..."
+  "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")"
+fi
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+if [ -n "${distributionSha256Sum-}" ]; then
+  distributionSha256Result=false
+  if [ "$MVN_CMD" = mvnd.sh ]; then
+    echo "Checksum validation is not supported for maven-mvnd." >&2
+    echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  elif command -v sha256sum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c - >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  elif command -v shasum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  else
+    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2
+    echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  fi
+  if [ $distributionSha256Result = false ]; then
+    echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2
+    echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2
+    exit 1
+  fi
+fi
+
+# unzip and move
+if command -v unzip >/dev/null; then
+  unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip"
+else
+  tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar"
+fi
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+actualDistributionDir=""
+
+# First try the expected directory name (for regular distributions)
+if [ -d "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" ]; then
+  if [ -f "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/bin/$MVN_CMD" ]; then
+    actualDistributionDir="$distributionUrlNameMain"
+  fi
+fi
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if [ -z "$actualDistributionDir" ]; then
+  # enable globbing to iterate over items
+  set +f
+  for dir in "$TMP_DOWNLOAD_DIR"/*; do
+    if [ -d "$dir" ]; then
+      if [ -f "$dir/bin/$MVN_CMD" ]; then
+        actualDistributionDir="$(basename "$dir")"
+        break
+      fi
+    fi
+  done
+  set -f
+fi
+
+if [ -z "$actualDistributionDir" ]; then
+  verbose "Contents of $TMP_DOWNLOAD_DIR:"
+  verbose "$(ls -la "$TMP_DOWNLOAD_DIR")"
+  die "Could not find Maven distribution directory in extracted archive"
+fi
+
+verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$actualDistributionDir/mvnw.url"
+mv -- "$TMP_DOWNLOAD_DIR/$actualDistributionDir" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME"
+
+clean || :
+exec_maven "$@"
@@ -0,0 +1,189 @@
+<# : batch portion
+@REM ----------------------------------------------------------------------------
+@REM Licensed to the Apache Software Foundation (ASF) under one
+@REM or more contributor license agreements.  See the NOTICE file
+@REM distributed with this work for additional information
+@REM regarding copyright ownership.  The ASF licenses this file
+@REM to you under the Apache License, Version 2.0 (the
+@REM "License"); you may not use this file except in compliance
+@REM with the License.  You may obtain a copy of the License at
+@REM
+@REM    http://www.apache.org/licenses/LICENSE-2.0
+@REM
+@REM Unless required by applicable law or agreed to in writing,
+@REM software distributed under the License is distributed on an
+@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+@REM KIND, either express or implied.  See the License for the
+@REM specific language governing permissions and limitations
+@REM under the License.
+@REM ----------------------------------------------------------------------------
+
+@REM ----------------------------------------------------------------------------
+@REM Apache Maven Wrapper startup batch script, version 3.3.4
+@REM
+@REM Optional ENV vars
+@REM   MVNW_REPOURL - repo url base for downloading maven distribution
+@REM   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+@REM   MVNW_VERBOSE - true: enable verbose log; others: silence the output
+@REM ----------------------------------------------------------------------------
+
+@IF "%__MVNW_ARG0_NAME__%"=="" (SET __MVNW_ARG0_NAME__=%~nx0)
+@SET __MVNW_CMD__=
+@SET __MVNW_ERROR__=
+@SET __MVNW_PSMODULEP_SAVE=%PSModulePath%
+@SET PSModulePath=
+@FOR /F "usebackq tokens=1* delims==" %%A IN (`powershell -noprofile "& {$scriptDir='%~dp0'; $script='%__MVNW_ARG0_NAME__%'; icm -ScriptBlock ([Scriptblock]::Create((Get-Content -Raw '%~f0'))) -NoNewScope}"`) DO @(
+  IF "%%A"=="MVN_CMD" (set __MVNW_CMD__=%%B) ELSE IF "%%B"=="" (echo %%A) ELSE (echo %%A=%%B)
+)
+@SET PSModulePath=%__MVNW_PSMODULEP_SAVE%
+@SET __MVNW_PSMODULEP_SAVE=
+@SET __MVNW_ARG0_NAME__=
+@SET MVNW_USERNAME=
+@SET MVNW_PASSWORD=
+@IF NOT "%__MVNW_CMD__%"=="" ("%__MVNW_CMD__%" %*)
+@echo Cannot start maven from wrapper >&2 && exit /b 1
+@GOTO :EOF
+: end batch / begin powershell #>
+
+$ErrorActionPreference = "Stop"
+if ($env:MVNW_VERBOSE -eq "true") {
+  $VerbosePreference = "Continue"
+}
+
+# calculate distributionUrl, requires .mvn/wrapper/maven-wrapper.properties
+$distributionUrl = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionUrl
+if (!$distributionUrl) {
+  Write-Error "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+}
+
+switch -wildcard -casesensitive ( $($distributionUrl -replace '^.*/','') ) {
+  "maven-mvnd-*" {
+    $USE_MVND = $true
+    $distributionUrl = $distributionUrl -replace '-bin\.[^.]*$',"-windows-amd64.zip"
+    $MVN_CMD = "mvnd.cmd"
+    break
+  }
+  default {
+    $USE_MVND = $false
+    $MVN_CMD = $script -replace '^mvnw','mvn'
+    break
+  }
+}
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+if ($env:MVNW_REPOURL) {
+  $MVNW_REPO_PATTERN = if ($USE_MVND -eq $False) { "/org/apache/maven/" } else { "/maven/mvnd/" }
+  $distributionUrl = "$env:MVNW_REPOURL$MVNW_REPO_PATTERN$($distributionUrl -replace "^.*$MVNW_REPO_PATTERN",'')"
+}
+$distributionUrlName = $distributionUrl -replace '^.*/',''
+$distributionUrlNameMain = $distributionUrlName -replace '\.[^.]*$','' -replace '-bin$',''
+
+$MAVEN_M2_PATH = "$HOME/.m2"
+if ($env:MAVEN_USER_HOME) {
+  $MAVEN_M2_PATH = "$env:MAVEN_USER_HOME"
+}
+
+if (-not (Test-Path -Path $MAVEN_M2_PATH)) {
+    New-Item -Path $MAVEN_M2_PATH -ItemType Directory | Out-Null
+}
+
+$MAVEN_WRAPPER_DISTS = $null
+if ((Get-Item $MAVEN_M2_PATH).Target[0] -eq $null) {
+  $MAVEN_WRAPPER_DISTS = "$MAVEN_M2_PATH/wrapper/dists"
+} else {
+  $MAVEN_WRAPPER_DISTS = (Get-Item $MAVEN_M2_PATH).Target[0] + "/wrapper/dists"
+}
+
+$MAVEN_HOME_PARENT = "$MAVEN_WRAPPER_DISTS/$distributionUrlNameMain"
+$MAVEN_HOME_NAME = ([System.Security.Cryptography.SHA256]::Create().ComputeHash([byte[]][char[]]$distributionUrl) | ForEach-Object {$_.ToString("x2")}) -join ''
+$MAVEN_HOME = "$MAVEN_HOME_PARENT/$MAVEN_HOME_NAME"
+
+if (Test-Path -Path "$MAVEN_HOME" -PathType Container) {
+  Write-Verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
+  exit $?
+}
+
+if (! $distributionUrlNameMain -or ($distributionUrlName -eq $distributionUrlNameMain)) {
+  Write-Error "distributionUrl is not valid, must end with *-bin.zip, but found $distributionUrl"
+}
+
+# prepare tmp dir
+$TMP_DOWNLOAD_DIR_HOLDER = New-TemporaryFile
+$TMP_DOWNLOAD_DIR = New-Item -Itemtype Directory -Path "$TMP_DOWNLOAD_DIR_HOLDER.dir"
+$TMP_DOWNLOAD_DIR_HOLDER.Delete() | Out-Null
+trap {
+  if ($TMP_DOWNLOAD_DIR.Exists) {
+    try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+    catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+  }
+}
+
+New-Item -Itemtype Directory -Path "$MAVEN_HOME_PARENT" -Force | Out-Null
+
+# Download and Install Apache Maven
+Write-Verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+Write-Verbose "Downloading from: $distributionUrl"
+Write-Verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+$webclient = New-Object System.Net.WebClient
+if ($env:MVNW_USERNAME -and $env:MVNW_PASSWORD) {
+  $webclient.Credentials = New-Object System.Net.NetworkCredential($env:MVNW_USERNAME, $env:MVNW_PASSWORD)
+}
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+$webclient.DownloadFile($distributionUrl, "$TMP_DOWNLOAD_DIR/$distributionUrlName") | Out-Null
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+$distributionSha256Sum = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionSha256Sum
+if ($distributionSha256Sum) {
+  if ($USE_MVND) {
+    Write-Error "Checksum validation is not supported for maven-mvnd. `nPlease disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties."
+  }
+  Import-Module $PSHOME\Modules\Microsoft.PowerShell.Utility -Function Get-FileHash
+  if ((Get-FileHash "$TMP_DOWNLOAD_DIR/$distributionUrlName" -Algorithm SHA256).Hash.ToLower() -ne $distributionSha256Sum) {
+    Write-Error "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised. If you updated your Maven version, you need to update the specified distributionSha256Sum property."
+  }
+}
+
+# unzip and move
+Expand-Archive "$TMP_DOWNLOAD_DIR/$distributionUrlName" -DestinationPath "$TMP_DOWNLOAD_DIR" | Out-Null
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+$actualDistributionDir = ""
+
+# First try the expected directory name (for regular distributions)
+$expectedPath = Join-Path "$TMP_DOWNLOAD_DIR" "$distributionUrlNameMain"
+$expectedMvnPath = Join-Path "$expectedPath" "bin/$MVN_CMD"
+if ((Test-Path -Path $expectedPath -PathType Container) -and (Test-Path -Path $expectedMvnPath -PathType Leaf)) {
+  $actualDistributionDir = $distributionUrlNameMain
+}
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if (!$actualDistributionDir) {
+  Get-ChildItem -Path "$TMP_DOWNLOAD_DIR" -Directory | ForEach-Object {
+    $testPath = Join-Path $_.FullName "bin/$MVN_CMD"
+    if (Test-Path -Path $testPath -PathType Leaf) {
+      $actualDistributionDir = $_.Name
+    }
+  }
+}
+
+if (!$actualDistributionDir) {
+  Write-Error "Could not find Maven distribution directory in extracted archive"
+}
+
+Write-Verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+Rename-Item -Path "$TMP_DOWNLOAD_DIR/$actualDistributionDir" -NewName $MAVEN_HOME_NAME | Out-Null
+try {
+  Move-Item -Path "$TMP_DOWNLOAD_DIR/$MAVEN_HOME_NAME" -Destination $MAVEN_HOME_PARENT | Out-Null
+} catch {
+  if (! (Test-Path -Path "$MAVEN_HOME" -PathType Container)) {
+    Write-Error "fail to move MAVEN_HOME"
+  }
+} finally {
+  try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+  catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+}
+
+Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
@@ -1,42 +1,113 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
-         http://maven.apache.org/xsd/maven-4.0.0.xsd">
-   <modelVersion>4.0.0</modelVersion>
+<!--
+  ~ QQQ - Low-code Application Framework for Engineers.
+  ~ Copyright (C) 2021-2026.  Kingsrook, LLC
+  ~ 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+  ~ contact@kingsrook.com
+  ~ https://github.com/Kingsrook/
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     https://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->

-   <groupId>com.kingsrook.qbits</groupId>
-   <artifactId>qbit-example-extension</artifactId>
-   <version>0.1.0-SNAPSHOT</version>
-   <packaging>jar</packaging>
-
-   <name>QBit Example Extension</name>
-   <description>Example Extension QBit - rename this for your QBit</description>
+<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>
+      <revision>0.1.0-SNAPSHOT</revision>
      <maven.compiler.source>21</maven.compiler.source>
      <maven.compiler.target>21</maven.compiler.target>
-      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-      <qqq.version>0.35.0</qqq.version>
+      <jacoco.version>0.8.15</jacoco.version>
+      <h2.version>2.2.224</h2.version>
   </properties>

+   <parent>
+      <groupId>com.kingsrook</groupId>
+      <artifactId>qbit-build-parent</artifactId>
+      <version>2.0.0</version>
+   </parent>
+
+   <groupId>com.kingsrook.qbits</groupId>
+   <artifactId>qbit-worm-audit</artifactId>
+   <version>${revision}</version>
+   <packaging>jar</packaging>
+
+   <name>QBit WORM Audit</name>
+   <description>QBit for write-once (WORM) audit in QQQ applications: database-enforced append-only audit tables, hash-chained tamper evidence with signed checkpoints, verification, and sealed exports to S3 Object Lock</description>
+   <url>https://github.com/QRun-IO/qbit-worm-audit</url>
+
+   <modelVersion>4.0.0</modelVersion>
+
+   <licenses>
+      <license>
+         <name>Apache License, Version 2.0</name>
+         <url>https://www.apache.org/licenses/LICENSE-2.0</url>
+         <distribution>repo</distribution>
+      </license>
+   </licenses>
+
+   <developers>
+      <developer>
+         <id>kingsrook</id>
+         <name>Kingsrook Team</name>
+         <email>contact@kingsrook.com</email>
+         <organization>Kingsrook, LLC</organization>
+         <organizationUrl>https://kingsrook.com</organizationUrl>
+      </developer>
+   </developers>
+
+   <scm>
+      <connection>scm:git:git://github.com/QRun-IO/qbit-worm-audit.git</connection>
+      <developerConnection>scm:git:ssh://github.com:QRun-IO/qbit-worm-audit.git</developerConnection>
+      <url>https://github.com/QRun-IO/qbit-worm-audit</url>
+      <tag>HEAD</tag>
+   </scm>
+
   <dependencies>
      <dependency>
         <groupId>com.kingsrook.qqq</groupId>
         <artifactId>qqq-backend-core</artifactId>
-         <version>${qqq.version}</version>
      </dependency>

+      <!-- The memory backend is included in qqq-backend-core. -->
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-module-rdbms</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-javalin</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-frontend-next</artifactId>
+         <version>1.0.0-RC.14</version>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.h2database</groupId>
+         <artifactId>h2</artifactId>
+         <version>${h2.version}</version>
+         <scope>test</scope>
+      </dependency>
      <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter</artifactId>
-         <version>5.10.0</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>org.assertj</groupId>
         <artifactId>assertj-core</artifactId>
-         <version>3.24.2</version>
+         <version>3.27.7</version>
         <scope>test</scope>
      </dependency>
   </dependencies>
@@ -45,14 +116,105 @@
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
-            <artifactId>maven-compiler-plugin</artifactId>
-            <version>3.11.0</version>
+            <artifactId>maven-checkstyle-plugin</artifactId>
+            <version>3.3.1</version>
+            <dependencies>
+               <dependency>
+                  <groupId>com.puppycrawl.tools</groupId>
+                  <artifactId>checkstyle</artifactId>
+                  <version>10.12.6</version>
+               </dependency>
+            </dependencies>
+            <configuration>
+               <configLocation>checkstyle/config.xml</configLocation>
+               <headerLocation>checkstyle/license.txt</headerLocation>
+               <encoding>UTF-8</encoding>
+               <consoleOutput>true</consoleOutput>
+               <failsOnError>false</failsOnError>
+               <failOnViolation>true</failOnViolation>
+               <violationSeverity>warning</violationSeverity>
+               <includeTestSourceDirectory>false</includeTestSourceDirectory>
+            </configuration>
+            <executions>
+               <execution>
+                  <id>validate</id>
+                  <phase>validate</phase>
+                  <goals>
+                     <goal>check</goal>
+                  </goals>
+               </execution>
+            </executions>
         </plugin>
         <plugin>
-            <groupId>org.apache.maven.plugins</groupId>
-            <artifactId>maven-surefire-plugin</artifactId>
-            <version>3.1.2</version>
+            <groupId>org.jacoco</groupId>
+            <artifactId>jacoco-maven-plugin</artifactId>
+            <version>${jacoco.version}</version>
+            <executions>
+               <execution>
+                  <id>prepare-agent</id>
+                  <goals>
+                     <goal>prepare-agent</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>report</id>
+                  <phase>verify</phase>
+                  <goals>
+                     <goal>report</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>check</id>
+                  <goals>
+                     <goal>check</goal>
+                  </goals>
+                  <configuration>
+                     <rules>
+                        <rule>
+                           <element>BUNDLE</element>
+                           <limits>
+                              <limit>
+                                 <counter>INSTRUCTION</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.70</minimum>
+                              </limit>
+                              <limit>
+                                 <counter>CLASS</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.90</minimum>
+                              </limit>
+                           </limits>
+                        </rule>
+                     </rules>
+                  </configuration>
+               </execution>
+            </executions>
         </plugin>
      </plugins>
   </build>
-</project>
+
+   <profiles>
+      <!-- QQQ 4.1 APIs until qbit-build-parent imports the 4.1 BOM (as in qbit-quick-search and qbit-cdn, ADR-0007). -->
+      <profile>
+         <id>qqq-snapshot</id>
+         <activation>
+            <activeByDefault>true</activeByDefault>
+         </activation>
+         <properties>
+            <!-- Latest QQQ RC on Maven Central (2026-10-13). -->
+            <qqq.snapshot.version>4.1.0-RC.5</qqq.snapshot.version>
+         </properties>
+         <dependencyManagement>
+            <dependencies>
+               <dependency>
+                  <groupId>com.kingsrook.qqq</groupId>
+                  <artifactId>qqq-bom-pom</artifactId>
+                  <version>${qqq.snapshot.version}</version>
+                  <type>pom</type>
+                  <scope>import</scope>
+               </dependency>
+            </dependencies>
+         </dependencyManagement>
+      </profile>
+   </profiles>
+</project>
@@ -1,75 +0,0 @@
-/*******************************************************************************
- ** Configuration for the Example Extension QBit.
- *******************************************************************************/
-package com.kingsrook.qbits.example;
-
-import java.util.List;
-
-import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfig;
-
-
-/*******************************************************************************
- ** Configuration class for the Example Extension QBit.
- *******************************************************************************/
-public class ExampleExtensionQBitConfig implements QBitConfig
-{
-   private String  targetTableName;
-   private Boolean enableFeatureX = true;
-
-
-
-   /*******************************************************************************
-    ** Validate configuration before QBit is produced.
-    *******************************************************************************/
-   @Override
-   public void validate(QInstance qInstance, List<String> errors)
-   {
-      if(targetTableName != null && qInstance.getTable(targetTableName) == null)
-      {
-         errors.add("Target table not found: " + targetTableName);
-      }
-   }
-
-
-
-   /*******************************************************************************
-    ** Getter for targetTableName
-    *******************************************************************************/
-   public String getTargetTableName()
-   {
-      return targetTableName;
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for targetTableName
-    *******************************************************************************/
-   public ExampleExtensionQBitConfig withTargetTableName(String targetTableName)
-   {
-      this.targetTableName = targetTableName;
-      return this;
-   }
-
-
-
-   /*******************************************************************************
-    ** Getter for enableFeatureX
-    *******************************************************************************/
-   public Boolean getEnableFeatureX()
-   {
-      return enableFeatureX;
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for enableFeatureX
-    *******************************************************************************/
-   public ExampleExtensionQBitConfig withEnableFeatureX(Boolean enableFeatureX)
-   {
-      this.enableFeatureX = enableFeatureX;
-      return this;
-   }
-}
@@ -1,66 +0,0 @@
-/*******************************************************************************
- ** Producer for the Example Extension QBit.
- *******************************************************************************/
-package com.kingsrook.qbits.example;
-
-import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitProducer;
-
-
-/*******************************************************************************
- ** Producer class for the Example Extension QBit.
- *******************************************************************************/
-public class ExampleExtensionQBitProducer implements QBitProducer
-{
-   public static final String GROUP_ID    = "com.kingsrook.qbits";
-   public static final String ARTIFACT_ID = "qbit-example-extension";
-   public static final String VERSION     = "0.1.0";
-
-   private ExampleExtensionQBitConfig config;
-
-
-
-   /*******************************************************************************
-    ** Produce this QBit into the given QInstance.
-    *******************************************************************************/
-   @Override
-   public void produce(QInstance qInstance, String namespace) throws QException
-   {
-      QBitMetaData qBitMetaData = new QBitMetaData()
-         .withGroupId(GROUP_ID)
-         .withArtifactId(ARTIFACT_ID)
-         .withVersion(VERSION)
-         .withNamespace(namespace)
-         .withConfig(config);
-
-      qInstance.addQBit(qBitMetaData);
-
-      if(config != null && config.getTargetTableName() != null)
-      {
-         applyTableCustomizations(qInstance, config.getTargetTableName());
-      }
-   }
-
-
-
-   /*******************************************************************************
-    ** Apply customizations to the target table.
-    *******************************************************************************/
-   private void applyTableCustomizations(QInstance qInstance, String tableName)
-   {
-      // Implement your extension logic here
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for config
-    *******************************************************************************/
-   public ExampleExtensionQBitProducer withConfig(ExampleExtensionQBitConfig config)
-   {
-      this.config = config;
-      return this;
-   }
-}
@@ -1,23 +0,0 @@
-/*******************************************************************************
- ** Example table customizer.
- *******************************************************************************/
-package com.kingsrook.qbits.example.customizers;
-
-import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
-
-
-/*******************************************************************************
- ** Example table customizer that adds behavior to existing tables.
- *******************************************************************************/
-public class ExampleTableCustomizer
-{
-
-   /*******************************************************************************
-    ** Apply customizations to the given table.
-    *******************************************************************************/
-   public void customize(QTableMetaData table)
-   {
-      // Example: Add audit tracking fields
-      // table.withField(new QFieldMetaData("createdAt", QFieldType.DATE_TIME));
-   }
-}
@@ -0,0 +1,81 @@
+/*
+ * 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.wormaudit;
+
+
+import com.kingsrook.qqq.backend.core.model.metadata.producers.MetaDataCustomizerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfig;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Configuration for the WORM audit qbit.
+ *******************************************************************************/
+public class WormAuditQBitConfig implements QBitConfig
+{
+   public static final int DEFAULT_RETENTION_YEARS = 6;
+
+   private MetaDataCustomizerInterface<QTableMetaData> tableMetaDataCustomizer;
+   private int retentionYears = DEFAULT_RETENTION_YEARS;
+
+
+
+   /*******************************************************************************
+    ** Getter for the optional table customizer.
+    *******************************************************************************/
+   @Override
+   public MetaDataCustomizerInterface<QTableMetaData> getTableMetaDataCustomizer()
+   {
+      return (tableMetaDataCustomizer);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for the optional table customizer.
+    *******************************************************************************/
+   public WormAuditQBitConfig withTableMetaDataCustomizer(MetaDataCustomizerInterface<QTableMetaData> tableMetaDataCustomizer)
+   {
+      this.tableMetaDataCustomizer = tableMetaDataCustomizer;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for the audit retention in years (HIPAA default: 6).
+    *******************************************************************************/
+   public int getRetentionYears()
+   {
+      return (retentionYears);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for the audit retention in years.
+    *******************************************************************************/
+   public WormAuditQBitConfig withRetentionYears(int retentionYears)
+   {
+      this.retentionYears = retentionYears;
+      return (this);
+   }
+}
@@ -0,0 +1,120 @@
+/*
+ * 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.wormaudit;
+
+
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaDataProducer;
+
+
+/*******************************************************************************
+ ** Entry point for the WORM audit qbit; no tables are produced yet.
+ *******************************************************************************/
+public class WormAuditQBitProducer implements QBitMetaDataProducer<WormAuditQBitConfig>
+{
+   public static final String GROUP_ID    = "com.kingsrook.qbits";
+   public static final String ARTIFACT_ID = "qbit-worm-audit";
+   public static final String VERSION     = "0.1.0";
+
+   private WormAuditQBitConfig qBitConfig;
+   private String namespace;
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for the config.
+    *******************************************************************************/
+   public WormAuditQBitProducer withQBitConfig(WormAuditQBitConfig config)
+   {
+      this.qBitConfig = config;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for the config.
+    *******************************************************************************/
+   @Override
+   public WormAuditQBitConfig getQBitConfig()
+   {
+      return (qBitConfig);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for the namespace.
+    *******************************************************************************/
+   public WormAuditQBitProducer withNamespace(String namespace)
+   {
+      this.namespace = namespace;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for the namespace.
+    *******************************************************************************/
+   @Override
+   public String getNamespace()
+   {
+      return (namespace);
+   }
+
+
+
+   /*******************************************************************************
+    ** Identity and configuration of this qbit.
+    *******************************************************************************/
+   @Override
+   public QBitMetaData getQBitMetaData()
+   {
+      return (new QBitMetaData().withGroupId(GROUP_ID).withArtifactId(ARTIFACT_ID).withVersion(VERSION).withNamespace(namespace).withConfig(qBitConfig));
+   }
+
+
+
+   /*******************************************************************************
+    ** Package-scanned producers have no config: skip them.
+    *******************************************************************************/
+   @Override
+   public boolean isEnabled()
+   {
+      return (qBitConfig != null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Register this qbit and return its metadata, without producing tables.
+    *******************************************************************************/
+   @Override
+   public MetaDataProducerMultiOutput produce(QInstance qInstance)
+   {
+      QBitMetaData qBit = getQBitMetaData();
+      qInstance.addQBit(qBit);
+      return (new MetaDataProducerMultiOutput().with(qBit));
+   }
+}
@@ -0,0 +1,90 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.wormaudit;
+
+
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.MetaDataCustomizerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Verify the scaffold's registration and configuration contract.
+ *******************************************************************************/
+class WormAuditQBitProducerTest
+{
+   /*******************************************************************************
+    ** Produce the identity and exact config into an otherwise empty instance.
+    *******************************************************************************/
+   @Test
+   void producesQBitWithoutTables()
+   {
+      QInstance instance = new QInstance();
+      WormAuditQBitConfig config = new WormAuditQBitConfig();
+      WormAuditQBitProducer producer = new WormAuditQBitProducer().withQBitConfig(config);
+      MetaDataProducerMultiOutput output = producer.produce(instance);
+      QBitMetaData qBit = instance.getQBits().get("com.kingsrook.qbits:qbit-worm-audit");
+
+      assertThat(qBit).isNotNull();
+      assertThat(qBit.getGroupId()).isEqualTo("com.kingsrook.qbits");
+      assertThat(qBit.getArtifactId()).isEqualTo("qbit-worm-audit");
+      assertThat(qBit.getVersion()).isEqualTo("0.1.0");
+      assertThat(qBit.getConfig()).isSameAs(config);
+      assertThat(producer.getQBitConfig()).isSameAs(config);
+      assertThat(producer.isEnabled()).isTrue();
+      assertThat(producer.getNamespace()).isNull();
+      assertThat(output.getEach(QBitMetaData.class)).containsExactly(qBit);
+      assertThat(output.getEach(QTableMetaData.class)).isEmpty();
+      assertThat(instance.getTables()).isEmpty();
+      assertThat(config.getRetentionYears()).isEqualTo(6);
+      assertThat(config.getTableMetaDataCustomizer()).isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** Configured instances may be namespaced; unconfigured scanning is disabled.
+    *******************************************************************************/
+   @Test
+   void supportsNamespacedConfiguration()
+   {
+      assertThat(new WormAuditQBitProducer().isEnabled()).isFalse();
+      MetaDataCustomizerInterface<QTableMetaData> customizer = (instance, table) -> table;
+      WormAuditQBitConfig config = new WormAuditQBitConfig()
+         .withTableMetaDataCustomizer(customizer)
+         .withRetentionYears(7);
+      WormAuditQBitProducer producer = new WormAuditQBitProducer()
+         .withQBitConfig(config)
+         .withNamespace("test");
+      QInstance instance = new QInstance();
+      producer.produce(instance);
+
+      assertThat(producer.getNamespace()).isEqualTo("test");
+      assertThat(instance.getQBits().get("com.kingsrook.qbits:qbit-worm-audit:test").getConfig()).isSameAs(config);
+      assertThat(config.getTableMetaDataCustomizer()).isSameAs(customizer);
+      assertThat(config.getRetentionYears()).isEqualTo(7);
+      assertThat(instance.getTables()).isEmpty();
+   }
+}
Author	SHA1	Message	Date
james.maesandClaude Opus 5.5	d25df1de0a	docs: the export policy also needs s3:PutObjectRetention Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-13 19:23:33 -05:00
james.maesandClaude Opus 5.5	bbac29e4d0	docs: WORM audit design spec Append-only audit tables enforced by Postgres triggers, a GRANT model and an audited retention purge; a single-writer hash chain with signed Merkle checkpoints, verification and daily alerting; sealed JSONL exports to S3 Object Lock (COMPLIANCE, 6 years); canonical content agreed with qbit-secured-data so only audit tokens are sealed. Owner decisions (2026-10-12): all recommendations accepted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-13 19:20:29 -05:00
james.maes	a6f4eb79f6	Merge pull request #2 from QRun-IO/feature/scaffold chore: repo-standard scaffold	2026-10-13 19:17:03 -05:00
james.maesandClaude Opus 5.5	8ab4fb686d	chore: repo-standard scaffold for qbit-worm-audit Pom on qbit-build-parent 2.0.0 with checkstyle and jacoco gates, Maven wrapper, CircleCI (orb 0.6.8, configure-package-install pre-step, GA-only publish_release, no hotfix publishing), release-rc caller workflow, dependabot, governance files, and the com.kingsrook.qbits.wormaudit package. Removes the template example. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-13 19:14:17 -05:00
james.maes	1212aedca6	Merge main into develop (bring develop up to main before the scaffold)	2026-10-13 19:12:10 -05:00
james.maes	87c171387a	chore: bump qqq to 0.40.0-SNAPSHOT	2026-01-10 21:05:39 -06:00