diff --git a/AGENTS.md b/AGENTS.md
index 225f677..cc83d94 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,7 +26,7 @@ Packages:
- `metadata`: `CmsTableBuilder` (tables, possible values, joins, child lists, associations, permission rules), `CmsAppBuilder` and `CmsAreas` (apps and homes).
- `home`: `CmsHomeRenderer` and `CmsHtml` (one renderer for every home; reads run with `PermissionEnforcement.ENFORCE`).
- `security`: `CmsRole`, `CmsSecurity`, `CmsOpenReadsPermissionChecker`.
-- Schema: `src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml`. Its changesets are append-only once released, and `docs/ddl/postgres.sql` is generated from it.
+- Schema: `src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml`. Its changesets are append-only once released: `CmsChangelogReleasedTest` fails the build when a released changeset differs from `src/test/resources/released/qbit-cms.changelog.released.yaml`, when one runs on every migration or waives its checksum, and when an install of the first release does not migrate on. When a release is cut, copy the changelog over that file in the same change. `docs/ddl/postgres.sql` is generated from the changelog.
## Naming (owner rule)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05348e4..56d6d53 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,4 +25,5 @@ All notable changes to this project are documented here. The format follows Keep
### Schema changes
- `1.0.0` baseline: a prefix-parameterized Liquibase changelog (`qbit-cms/db/changelog/qbit-cms.changelog.yaml`, logical path `qbit-cms/changelog`). It creates the CORE tables with the kof22 column types, adds their foreign keys and indexes, and seeds generic reference data. Feature sections are gated by `cms.features`, and a name collision halts the install. Reference DDL is in `docs/ddl/postgres.sql`.
- `1.0.0` content tables, appended to the same changelog: `1.0.0-create-
` for the eighteen tables of `MEDIA`, `BLOG`, `PROJECTS` and `PHOTOS`, `1.0.0-constraints-` for each feature's foreign keys and indexes, `1.0.0-constraints-blog-projects` and `1.0.0-constraints-photos-projects` for the links between two features, and `1.0.0-seed-media_type` and `1.0.0-seed-blog_type` for generic reference data. Each is gated by `cms.features` and by the features it needs. `1.0.0-guard-existing-content-tables` halts the install when a table with one of these names already exists; it runs once, not on every run.
-- **Changed, on purpose, in a released changeset:** `1.0.0-guard-existing-tables` no longer has `runAlways`. It rewrote its `DATABASECHANGELOG` row on every migration, so a second migration was never a no-op and a rollback by count began with it; a host whose migrations must be repeatable could not include this changelog and had to copy the tables instead. It now runs once, before the tables are created, and carries `validCheckSum: ANY` so an install that already ran it migrates on unchanged (`CmsInstallTest.testRerunIsNoop` covers both). A table that appears later under a qbit name still stops the install, at its `createTable`. Check constraints as in kof22: the value-list columns of `media_type`, `blog_post_version` and `project` (the project status check is new), `media_type.max_file_size_mb` above zero and the focal point of a project's image between 0 and 100. `project_category.section` is optional (kof22 requires it); latitude and longitude columns are `DOUBLE PRECISION` as in kof22. A host that already runs `CORE` gets the content tables at its next migration run unless its `cms.features` leaves them out.
+- **Changed, on purpose, in a released changeset (the one recorded exception to "released changesets never change"):** `1.0.0-guard-existing-tables` no longer has `runAlways`. It rewrote its `DATABASECHANGELOG` row on every migration, so a second migration was never a no-op and a rollback by count began with it; a host whose migrations must be repeatable could not include the changelog. Only that attribute changed: the changeset's changes are what they were, so the checksum an existing install recorded is still its checksum and nothing is waived (`0.1.0-RC.3` carried `validCheckSum: ANY`, which was not needed and is removed). `CmsChangelogReleasedTest` migrates an install made by the `0.1.0-RC.2` changelog as tagged and asserts that its history rows are untouched, and from now on fails the build when any released changeset differs from `src/test/resources/released/qbit-cms.changelog.released.yaml`, runs on every migration or waives its checksum. What the guard no longer does: check for a name collision again at a later migration. A feature switched on later still cannot adopt a foreign table, because creating a table that exists fails; the message is the database's and not the guard's.
+- Check constraints as in kof22: the value-list columns of `media_type`, `blog_post_version` and `project` (the project status check is new), `media_type.max_file_size_mb` above zero and the focal point of a project's image between 0 and 100. `project_category.section` is optional (kof22 requires it); latitude and longitude columns are `DOUBLE PRECISION` as in kof22. A host that already runs `CORE` gets the content tables at its next migration run unless its `cms.features` leaves them out.
diff --git a/CLAUDE.md b/CLAUDE.md
index ef560f1..24085a5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -26,7 +26,7 @@ Packages:
- `metadata`: `CmsTableBuilder` (tables, possible values, joins, child lists, associations, permission rules), `CmsAppBuilder` and `CmsAreas` (apps and homes).
- `home`: `CmsHomeRenderer` and `CmsHtml` (one renderer for every home; reads run with `PermissionEnforcement.ENFORCE`).
- `security`: `CmsRole`, `CmsSecurity`, `CmsOpenReadsPermissionChecker`.
-- Schema: `src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml`. Its changesets are append-only once released, and `docs/ddl/postgres.sql` is generated from it.
+- Schema: `src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml`. Its changesets are append-only once released: `CmsChangelogReleasedTest` fails the build when a released changeset differs from `src/test/resources/released/qbit-cms.changelog.released.yaml`, when one runs on every migration or waives its checksum, and when an install of the first release does not migrate on. When a release is cut, copy the changelog over that file in the same change. `docs/ddl/postgres.sql` is generated from the changelog.
## Naming (owner rule)
diff --git a/src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml b/src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml
index ad8a41e..0e871b5 100644
--- a/src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml
+++ b/src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml
@@ -6,7 +6,9 @@
# cms.tablePrefix table name prefix, must equal CmsQBitConfig.tableNamePrefix (default cms_)
# cms.features comma-separated CmsFeature names to install (default: all)
# cms.seedReferenceData insert the generic redirect, page and section types (default true)
-# Changesets are only ever appended; released changesets never change.
+# Changesets are only ever appended; released changesets never change (CmsChangelogReleasedTest holds the build to
+# it). One exception is recorded: 0.1.0-RC.3 took runAlways off 1.0.0-guard-existing-tables; its changes, and so
+# its checksum, are what they were.
databaseChangeLog:
- property: { name: cms.tablePrefix, value: cms_ }
- property: { name: cms.features, value: "CORE,MEDIA,BLOG,PROJECTS,PHOTOS,PUBLISHING,STREAM" }
@@ -16,12 +18,12 @@ databaseChangeLog:
# changelog (a name collision): choose another cms.tablePrefix.
# It runs once, before the tables are created. Up to 0.1.0-RC.2 it ran on every migration (runAlways), which made
# every run rewrite its row in DATABASECHANGELOG: a second migration was never a no-op and a rollback by count
- # began with this changeset. An install that already ran it keeps its row; validCheckSum accepts what it recorded.
+ # began with this changeset. An install that already ran it keeps its row: the changes below are unchanged, so the
+ # checksum it recorded is still this changeset's, and nothing is waived.
- changeSet:
id: 1.0.0-guard-existing-tables
author: qbit-cms
logicalFilePath: qbit-cms/changelog
- validCheckSum: ANY
preConditions:
- onFail: HALT
- onFailMessage: "A table named ${cms.tablePrefix} exists but was not created by qbit-cms; set a different cms.tablePrefix"
diff --git a/src/test/java/com/kingsrook/qbits/cms/CmsChangelogReleasedTest.java b/src/test/java/com/kingsrook/qbits/cms/CmsChangelogReleasedTest.java
new file mode 100644
index 0000000..b15dba5
--- /dev/null
+++ b/src/test/java/com/kingsrook/qbits/cms/CmsChangelogReleasedTest.java
@@ -0,0 +1,157 @@
+/*
+ * Copyright © 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
+ *
+ * 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.
+ */
+
+package com.kingsrook.qbits.cms;
+
+
+import java.io.InputStream;
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.Statement;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
+import org.junit.jupiter.api.Test;
+import org.yaml.snakeyaml.Yaml;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The changelog's contract with installs that already ran it: a released
+ ** changeset never changes, and new versions only append.
+ **
+ ** Two files under src/test/resources/released hold what has shipped:
+ ** - qbit-cms.changelog-0.1.0-RC.2.yaml, the first release, as tagged. An
+ ** install made by it must migrate on with the current changelog, with no
+ ** checksum waiver, and its history must stay as it was.
+ ** - qbit-cms.changelog.released.yaml, the changelog as of the latest release.
+ ** Every changeset in it must be in the current changelog unchanged and in
+ ** the same order; new changesets go after them. When a release is cut, copy
+ ** the current changelog over that file in the same change.
+ **
+ ** One exception is recorded: 0.1.0-RC.3 took runAlways off the first guard
+ ** changeset (it rewrote its history row on every migration). Its changes are
+ ** what they were, so its checksum is the one existing installs recorded.
+ *******************************************************************************/
+class CmsChangelogReleasedTest
+{
+ private static final String FIRST_RELEASE = "released/qbit-cms.changelog-0.1.0-RC.2.yaml";
+ private static final String RELEASED = "released/qbit-cms.changelog.released.yaml";
+ private static final String GUARD = "1.0.0-guard-existing-tables";
+
+
+
+ /*******************************************************************************
+ ** An install of the first release, migrated more than once as its guard did,
+ ** migrates on with the current changelog: no checksum is waived, the rows it
+ ** recorded are untouched, the content tables arrive, and a further migration
+ ** changes nothing.
+ *******************************************************************************/
+ @Test
+ void testAnInstallOfTheFirstReleaseMigratesOn() throws Exception
+ {
+ RDBMSBackendMetaData backend = CmsTestSupport.h2Backend();
+ CmsTestSupport.migrate(backend, FIRST_RELEASE, Map.of());
+ CmsTestSupport.migrate(backend, FIRST_RELEASE, Map.of());
+ Map first = history(backend);
+ assertThat(first).containsKey(GUARD);
+ assertThat(first.get(GUARD)).as("the first release ran its guard on every migration").contains("|RERAN");
+
+ CmsTestSupport.migrate(backend, Map.of());
+ Map upgraded = history(backend);
+ for(Map.Entry row : first.entrySet())
+ {
+ assertThat(upgraded.get(row.getKey())).as("the history row of " + row.getKey() + " after the upgrade").isEqualTo(row.getValue());
+ }
+ assertThat(upgraded.keySet()).as("the content tables are created by the upgrade").contains("1.0.0-create-media", "1.0.0-create-blog_post");
+
+ CmsTestSupport.migrate(backend, Map.of());
+ assertThat(history(backend)).as("the history after a further migration").isEqualTo(upgraded);
+ }
+
+
+
+ /*******************************************************************************
+ ** Every released changeset is in the current changelog, unchanged and in the
+ ** same order; whatever is new comes after them. None runs on every migration.
+ *******************************************************************************/
+ @Test
+ void testReleasedChangesetsNeverChange() throws Exception
+ {
+ List