fix(settings): keep seed() as deprecated API, fix docs

Restore WormAuditSettings.seed() (public since RC.2) as @Deprecated: still the
way memory and H2 hosts create row 1. Fix README, CHANGELOG order and UPGRADE.

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

CHANGELOG.md

@@ -6,11 +6,7 @@ All notable changes are documented here, following [Keep a Changelog](https://ke
 
 ### Added
 
-- Guided empty states: `help/qbit-worm-audit.yaml` (QQQ help-bundle format) gives the app and all six tables a summary and a "How rows get created" section, applied by the `WormAuditHelp` stand-in (`STAND-IN(core=QRun-IO/qqq#1198)`) without replacing host help. `WormAuditTablesGuardrailTest` pins runtime use, seeding or a documented reason, and help for every table; `WormAuditSettingsSeedTest` runs the script's settings seed on H2.
-
-### Removed
-
-- `WormAuditSettings.seed(config)`: dead code (nothing in `src/main` called it). The database script is the single seed, and `read()` already falls back to the configured values when the row is absent. Hosts do not call it.
+- Guided empty states: `help/qbit-worm-audit.yaml` (QQQ help-bundle format) gives the app and all six tables a summary and a "How rows get created" section, applied by the `WormAuditHelp` stand-in (`STAND-IN(core=QRun-IO/qqq#1198, removeBy=4.1.0-RC.7)`) without replacing host help. `WormAuditTablesGuardrailTest` pins runtime use, seeding or a documented reason, and help for every table; `WormAuditSettingsSeedTest` runs the script's settings seed on H2.
 
 - RC.2 settings: editable, FIELD-audited singleton with insert-only defaults, validation, separate edit permission and a 30-second effective-settings cache. Schedules load at startup.
 - GOVERNANCE exports with 30-day default retention; per-export retention verification, administrator-bypass diagnostics, home warnings and documented COMPLIANCE transition.
@@ -32,3 +28,7 @@ All notable changes are documented here, following [Keep a Changelog](https://ke
 ### Fixed
 
 - Keep runtime signing/trust objects and storage suppliers out of serialized metadata so signed-chain record child lists render successfully.
+
+### Deprecated
+
+- `WormAuditSettings.seed(config)` is deprecated for PostgreSQL hosts, whose database script (`worm-audit:10`) already seeds row 1; it remains supported for memory and H2 hosts. `read()` falls back to the configured values while the row is absent.

README.md

@@ -110,8 +110,9 @@ absent. Historical checkpoints remain valid after changing their creation cadenc
 
 Changeset `worm-audit:10` creates and seeds the table with `INSERT ... SELECT ... WHERE NOT
 EXISTS`; rerunning it never overwrites an administrator change. The renderer seeds from the
-host config. Memory hosts and the demo can call `WormAuditSettings.seed(config)` for the same
-insert-only behavior during single-threaded startup.
+host config. Memory and H2 hosts, whose settings table cannot take generic inserts, can still call
+`WormAuditSettings.seed(config)` for the same insert-only behavior during single-threaded
+startup (deprecated for PostgreSQL hosts, which get the row from the script).
 
 `audit_retention_years` does **not** rewrite the database purge function. The home warns if
 it differs from the compiled interval; changing that interval requires a reviewed migration.

UPGRADE.md

@@ -4,4 +4,4 @@
 
 Nothing to do. The qbit applies `help/qbit-worm-audit.yaml` at the end of `produce()`, filling only help slots the host has not set. No schema or seed changes: the settings row is still seeded by the database script (changeset `worm-audit:10`) and nothing else is seeded.
 
-`WormAuditSettings.seed(config)` was removed (dead code). A host that called it should rely on the database script's seed; the settings reader falls back to the configured values while the row is absent.
+`WormAuditSettings.seed(config)` is now `@Deprecated` for PostgreSQL hosts (the script seeds row 1). It still works and remains the way for memory and H2 hosts to create row 1. The settings reader falls back to the configured values while the row is absent.

src/main/java/com/kingsrook/qbits/wormaudit/WormAuditSettings.java

@@ -89,6 +89,27 @@ public class WormAuditSettings
    }
 
 
+   /*******************************************************************************
+    ** Seed the singleton only when absent; never overwrite an administrator edit.
+    ** The database script (changeset worm-audit:10) is the normal seed; this remains
+    ** for memory and H2 hosts, whose settings table cannot take generic inserts.
+    **
+    ** @deprecated for PostgreSQL hosts, which get row 1 from the database script;
+    ** still the supported way to create row 1 on memory and H2 hosts. Reads already
+    ** fall back to the configured values while the row is absent.
+    *******************************************************************************/
+   @Deprecated
+   public static void seed(WormAuditQBitConfig config) throws com.kingsrook.qqq.backend.core.exceptions.QException
+   {
+      var store = new AuditStore(null);
+      if(store.get(WormAuditTables.SETTINGS, 1) == null)
+      {
+         store.insert(WormAuditTables.SETTINGS, java.util.List.of(defaults(config)));
+      }
+      config.invalidateSettings();
+   }
+
+
    /*******************************************************************************
     ** Read at most once per 30 seconds, isolated by QInstance identity.
     *******************************************************************************/

src/test/java/com/kingsrook/qbits/wormaudit/WormAuditSettingsSeedTest.java

@@ -40,9 +40,9 @@ import static org.assertj.core.api.Assertions.assertThat;
  ** run on H2; this runs the settings table's CREATE and its seed statement as
  ** the script renders them, on H2 in PostgreSQL mode: the row appears with the
  ** host's values, a second run inserts nothing, and an edit survives.
- ** This is the only seed: WormAuditSettings.seed() was dead code (nothing in
- ** src/main called it) and was removed, because WormAuditSettings.read() already
- ** falls back to the configured values when the row is absent.
+ ** WormAuditSettings.seed() is deprecated (nothing in src/main calls it) but still
+ ** works for memory and H2 hosts; WormAuditSettings.read() falls back to the
+ ** configured values while the row is absent.
  *******************************************************************************/
 class WormAuditSettingsSeedTest
 {
@@ -79,6 +79,23 @@ class WormAuditSettingsSeedTest
 
 
 
+   /*******************************************************************************
+    ** The deprecated public seed() still creates row 1 once and keeps edits.
+    *******************************************************************************/
+   @Test
+   @SuppressWarnings("deprecation")
+   void deprecatedSeedStillWorksForMemoryHosts() throws Exception
+   {
+      var config = new WormAuditQBitConfig().withRetentionYears(8);
+      WormAuditTestSupport.init(config);
+      WormAuditSettings.seed(config);
+      assertThat(WormAuditTestSupport.STORE.get("worm_audit_settings", 1).getValueInteger("audit_retention_years")).isEqualTo(8);
+      WormAuditSettings.seed(config);
+      assertThat(WormAuditTestSupport.STORE.get("worm_audit_settings", 1)).isNotNull();
+   }
+
+
+
    /*******************************************************************************
     ** The script seeds nothing but the settings table: its only top-level INSERT is the
  ** settings seed (the indented purge INSERTs are the purge function writing its log).