@bygghammar/cms-platform 0.91.1 → 0.92.1

package/CHANGELOG.md

@@ -8,6 +8,131 @@ matches `package.json` exactly. See
 Versions 0.1.0 through 0.78.0 predate this repository and were reconstructed
 from the published npm tarballs.
 
+## 0.92.1
+
+- Fix the page-builder save and publish RPC call by removing the unsupported
+  `_source_page_id` argument. The database supplies the source page internally,
+  preserving self-reveal protection. No migration is added or changed, and
+  platform contract v3 is unchanged.
+- Clarify publication RPC errors so an argument mismatch is not presented as
+  proof that migrations must be replayed. Include only a recognized diagnostic
+  code and request a schema comparison before applying changes.
+
+## 0.92.0
+
+**Breaking: platform contract v3.** A site pinned to this package must call
+`assertPlatformContract(3)`, and its database must have applied
+`20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql`. Upgrading a live
+site is an ordered procedure, not a deploy — read the next four bullets before
+starting one.
+
+- **The publication reader changed, and on some sites that takes a page down.**
+  `0.90.0-m7.12` dropped closed publication rows and then took the newest of
+  what was left; v3 takes the newest row that has started and only then asks
+  whether it is still open. The new order is what makes a scheduled window mean
+  what it says, but where a page's newest row has expired and an older one is
+  still open, the old reader served the open row and the new one serves nothing.
+  The page goes dark on deploy with no error anywhere.
+- **`cms-review` is the procedure for that**, and ships as a `bin` of this
+  package. `cms-review scan` reads the site and classifies every live page;
+  pages the upgrade can keep alive on its own are repaired without being asked
+  about, and the three classifications that carry two opposite intentions —
+  contradictory rows, the two readers serving different versions, and a page
+  whose only window has not opened yet — stop the upgrade until somebody
+  answers. `cms-review approve` seals the answers to one database, one release,
+  one package version, one migration file and one hour; the migration recomputes
+  all of it and refuses an approval that no longer matches. Full procedure in
+  `docs/PUBLICATION-REVIEW.md`.
+- **`cms-review record` carries an approval to a machine with no psql prompt.**
+  A self-hosted VPS installs the approval as a file and reads it back with a
+  shell function in the deployment template; that file used to be written by
+  hand against a format nobody generated, and four things about it disagreed
+  with what `cms-review` emitted — hyphenated nonces, millisecond timestamps, a
+  missing `decision_count`, and two email addresses the record had no slot for,
+  so the migration recorded a reviewed change as unattended. Both roads are now
+  rendered from one builder, so they cannot drift again. The record is nineteen
+  ordered `key=value` lines, printable ASCII, checked field by field before it
+  is printed. `decisions` is canonical JSON, which is what makes the shell's
+  `sha256sum` of that text, the migration's digest of the same value as `jsonb`
+  and `decisions_digest` agree; a zero-decision approval is expressible as
+  `decision_count=0` with `decisions=[]`. `ops/approval-record-roundtrip.mjs`
+  proves the whole path end to end against the deployment template's real
+  reader and a real PostgreSQL; it is `bun run test:roundtrip`, and step 3 of
+  the release process asks for it whenever the record's format moves.
+- **Two identities, and they are not interchangeable.** `database_identity`
+  names the cluster, which is what the deployment tooling checks; the new
+  `review_database_identity` names the database the scan actually read, which
+  is what the migration checks and what it now requires. A cluster holds more
+  than one database and only one of them was reviewed. The run records the
+  sharper one, in `cms_publication_review_runs.review_database_identity` — a
+  column named for the setting it holds, rather than for the other one.
+- **Release order, and it is not optional.** Apply every missing canonical
+  migration; scan, review and apply the publication decisions; then deploy this
+  package with the site pinned to contract v3. The migration itself publishes,
+  unpublishes and edits nothing — applying it changes what the site can be
+  *asked*, not what it serves — which is what makes the first step safe to take
+  ahead of the deploy.
+- **A site with nothing to decide upgrades with no ceremony.** The migration
+  counts the pages needing an answer first; where there are none it is an
+  ordinary schema change. Where there is even one and no approval was supplied,
+  it stops and names what it did not get rather than choosing.
+- **Five facts that used to be one.** "The deployment succeeded" stood for the
+  migration having run, the schema therefore offering a capability, somebody
+  having understood what the new reader does to the existing rows, those
+  decisions having been applied, and the routes having been activated. Each now
+  has its own record and the later ones refuse to be written while an earlier
+  one is missing. `cms_schema_capabilities` is written by the migration that
+  makes it true, so it cannot drift from the schema it describes.
+- **Duplicating a page is one transaction.** It was a sequence of unrelated
+  inserts that could leave a page with no version, or two copies behind one
+  retried click. `cms_duplicate_page` takes the page lock, checks that the
+  source still holds the version and the content the caller read, and records
+  the copy against a caller-supplied idempotency key inside the same
+  transaction — so a retry returns the first copy instead of making a second,
+  and a rollback leaves the key unspent.
+- **A route has one owner.** Two pages could hold the same URL, because nothing
+  in the database was responsible for the pair. `(origin, path)` is now a
+  primary key, and a release's claims are written against it. A clash comes
+  back as a value listing every colliding route and changes nothing, rather
+  than raising on the first one — a deploy can then report every clash at once
+  instead of sending an operator to find the rest by hand.
+- **One lock order everywhere**: pages, then publications, then review, with the
+  route advisory lock taken after the page lock. Two deploys racing for the same
+  route take turns instead of interleaving.
+- **One list of canonical migrations.** Two modules used to carry the same sixty
+  names, and the test comparing them could only report that they had already
+  drifted apart — it could not say which was right. The catalog is now
+  generated from the `migrations/` directory with a digest per file, and
+  `bun run manifest:check` fails the build — and the release — when the file
+  and the catalog disagree. `cms-review` cross-checks it before sealing
+  anything, because an approval binds itself to what the package ships.
+- **Replace mode clears once, before anything is written.** It used to delete
+  inside the per-table loop, so a later table's `DELETE` could remove rows an
+  earlier one had just written, and a table the archive said nothing about was
+  skipped before the delete ran — leaving it populated in the one mode whose
+  whole job is to replace it. The selected groups are now emptied in a single
+  pass in reverse dependency order, with deferred pointers released first, and
+  a clear that fails aborts that table's children instead of warning.
+- **Breaking for callers of `backup/restore-core`**: deciding what to clear and
+  rendering it are now two functions. `buildClearPlan(groups)` returns the
+  steps, and it is the one that drops insert-only tables; `buildClear(step)`
+  renders one and always answers a statement, where it used to be
+  `Statement | null` and returned null for an insert-only table. TypeScript
+  rejects the old call, but a suite that only runs tests will see a `DELETE`
+  for a table that used to be spared — so read `buildClearPlan` first if you
+  clear tables yourself.
+- **Archive schema 3.** Backups written by this version declare
+  `SCHEMA_VERSION` 3 and carry the three publication-review tables. The archive
+  *format* is unchanged at 2, so a 0.91.x build still opens the container — and
+  then refuses it, because it has no branch that says what schema 3 means. That
+  refusal is the point: an archive is read by a build that knows what every
+  version in it meant, or it is not read.
+- **Restoring a 0.91.x backup into a v3 site is supported.** Schema 2 has no
+  review history, no page status and no publication signature, but everything
+  it does say still means what it said, and what it omits is recoverable by
+  scanning the restored content. The restore records a reconciliation run
+  rather than inventing a review that never happened.
+
 ## 0.91.1
 
 - Documentation correction, and nothing else. The npm-facing `README.md` said

package/README.md

@@ -43,6 +43,7 @@ exactly as it did before locks existed.
 | `docs/MEDIA-FOLDERS.md` | Automatic month folders, custom upload folders and their sanitising, library browsing |
 | `docs/GOOGLE-SHEETS.md` | Service-account form delivery, the connection test, and the server variables it needs |
 | `docs/TYPOGRAPHY.md` | Independent Google Fonts for the menu and the footer |
+| `docs/PUBLICATION-REVIEW.md` | The `cms-review` procedure for upgrading a live site to contract v3 |
 
 ## Server variables
 
@@ -59,21 +60,31 @@ related is ever read in the browser, and the font picker needs no API key. See
   releases are always compatible.
 - `PLATFORM_CONTRACT_VERSION` (`platform/contract`) is bumped when a shared
   screen starts requiring schema or adapter capabilities an older site lacks.
-  Sites pin it in a test. It is **v2**: page saves, publishing, trashing and
-  restoring go through database functions. Upgrading straight from the last
-  pre-v2 published package, `0.90.0-m7.12`, means applying all three new
-  canonical migrations, in chronological order:
+  Sites pin it in a test. It is **v3**: page saves, publishing, trashing and
+  restoring go through database functions (v2), and a release records the five
+  facts it used to assert with one sentence — migration applied, schema
+  capability, publication scan, decisions applied, routes activated — as five
+  separate records the later of which refuse to be written without the earlier
+  (v3). Upgrading straight from the last pre-v2 published package,
+  `0.90.0-m7.12`, means applying all four new canonical migrations, in
+  chronological order:
 
   1. `20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql`
   2. `20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql`
   3. `20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql`
+  4. `20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql`
 
-  The last two are the pair that establishes contract-v2 publication
+  Files 2 and 3 are the pair that establishes contract-v2 publication
   behaviour, but the first is canonical schema too, so applying only the pair
-  still leaves `missingMigrations` and `compareSchema` reporting drift. Apply
-  them before the v2 package is deployed, then verify the two things
-  separately: `missingMigrations(applied)` reports nothing missing, **and**
-  `assertPlatformContract(2)` passes. The second only compares version numbers
+  still leaves `missingMigrations` and `compareSchema` reporting drift. File 4
+  adds contract v3: the release ledger, the review model, the route claims, one
+  lock order every page mutation follows, and duplication as a single
+  transaction. It replaces five publication function bodies at the signatures
+  they already have, without changing what any of them decides, so nothing a
+  visitor sees today changes.
+  Apply them before the v3 package is deployed, then verify separately:
+  `missingMigrations(applied)` reports nothing missing, **and**
+  `assertPlatformContract(3)` passes. The second only compares version numbers
   in the site's own code and never reads the database, so it is no substitute
   for the first. `docs/NEW-SITE.md` gives the full order.
 - `migrations/` is schema only. Site content, SEO copy and seeds never belong

package/docs/NEW-SITE.md

@@ -34,34 +34,42 @@ Add one test that pins the contract version the site was built against and one
 that asserts `missingMigrations(appliedFilenames)` is empty. See
 `tests/platform-contract.test.ts` in any existing site for the exact shape.
 
-The current contract is **v2**, because saving a page version — an ordinary
-draft save included — is a single database function call with no JavaScript
-fallback. Three canonical migrations are new since the last published
-`0.90.0-m7.12` package, so a site upgrading from that baseline is missing all
-three:
+The current contract is **v3**. It is v2 for the reason v2 existed — saving a
+page version, an ordinary draft save included, is a single database function
+call with no JavaScript fallback — and v3 because a release now records the
+five facts it used to assert with one sentence. "The deployment succeeded" used
+to mean, all at once: the migration ran, the schema therefore offers a
+capability, somebody looked at the existing publication rows and understood
+what the new reader does differently to them, those decisions were applied, and
+the routes were activated. Each fails on its own, so each has its own record,
+and the later ones refuse to be written while an earlier one is missing.
+
+Four canonical migrations are new since the last published `0.90.0-m7.12`
+package, so a site upgrading from that baseline is missing all four:
 
 | File | Adds |
 | --- | --- |
 | `20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql` | restates the `draft` default, records the `pages.status` column semantics at that migration step, and adds two partial `pages` indexes: one on `key` for undeleted status-published rows, one on `status`/`updated_at` for undeleted rows |
 | `20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql` | `page_publications` — the row that decides what is public — the backfill for pages that were already live, and the first transactional page functions |
 | `20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql` | the rest of the transactional page lifecycle: reveals, trash, restore and cancellation, plus two repair `UPDATE`s |
+| `20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql` | contract v3: the installation identity, the schema-capability record, the canonical digest functions, the publication review model, the route claims, the readiness and activation records, one lock order every page mutation follows, and `cms_duplicate_page` |
 
-The last two are the contract-v2 publication pair: they are what
-`PLATFORM_CONTRACT_VERSION = 2` means. All three are in the canonical schema
-manifest, though, so `missingMigrations` and `compareSchema` report every one
-that has not been applied — applying only the pair still leaves the schema out
-of sync. Go out in this order, and not in another:
+Files two and three are the contract-v2 publication pair, and the fourth is
+contract v3. All four are in the canonical schema manifest, so
+`missingMigrations` and `compareSchema` report every one that has not been
+applied — applying only the pair still leaves the schema out of sync. Go out in
+this order, and not in another:
 
 1. Apply every missing canonical migration. Upgrading from `0.90.0-m7.12`, that
-   is all three files above, in chronological order.
-2. Deploy the package and the site pinned to v2.
+   is all four files above, in chronological order.
+2. Deploy the package and the site pinned to v3.
 3. Verify both: `missingMigrations(applied)` is empty, and
-   `assertPlatformContract(2)` passes. The second compares two version numbers
+   `assertPlatformContract(3)` passes. The second compares two version numbers
    in the site's own code and never reads the database, so it is no substitute
    for the first.
 4. Let editors back in.
 
-The migrations are designed to be applied before the v2 package is deployed,
+The migrations are designed to be applied before the v3 package is deployed,
 and the still-running m7.12 package remains compatible during that ordered
 rollout. They are not pure DDL and not function-only: the set carries an
 `ALTER … SET DEFAULT`, indexes and a column comment, a backfill `INSERT`, two
@@ -117,12 +125,19 @@ Wrap the shared server cores in the site's own `createServerFn` files:
 | `server/forms-core` | form definitions, versions, settings, delivery log |
 | `server/redirects-core` | path normalisation and redirect writes |
 | `server/page-seo-core` | slug conflicts and slug-change 301s |
+| `site/route-index` | the one spelling of a page's address, shared by all of the above |
 | `server/media-usage-core` | usage scan and remote import |
 | `server/media-cleanup-core` | duplicate/rename planning and apply |
 
 The site supplies clients, storage and page-key → path maps; the package owns
 the rules. Keep privileged clients inside handlers.
 
+`resolvePathCore` and `detectSlugConflictsCore` both need `defaultLocale`, and
+`resolvePathCore` also needs the `locale` the site derived from the request's
+domain. Pass the site's real values: a wrong default locale moves every
+non-default page's prefix, and passing the default locale for every request
+turns a locale domain back into a site that serves one language.
+
 ## 7. Backoffice routes
 
 Each backoffice route is a thin adapter around the package view

package/docs/PAGES.md

@@ -30,6 +30,41 @@ the same question of the same rows.
 
 Knowing the URL gets a visitor a 404.
 
+## One address, spelled one way
+
+A page's address is the locale prefix plus its slug, and every part of the
+platform that needs to know one asks the same two functions for it:
+`servedPath` builds it and `normalizeRoutePath` spells it. The site's own link
+building, the conflict check an editor sees while typing a slug, the resolver
+that turns an incoming request into a page and the route claims written at
+deploy all go through that pair, in `site/route-index`.
+
+They used to have three opinions between them, and each disagreement was a bug
+you could see from the outside:
+
+- The resolver put every locale's slugs into one map, first one in wins. Two
+  pages sharing a slug in different locales were one page, and the loser was
+  unreachable at every address it was supposed to answer at.
+- The conflict check compared bare slug strings, one locale at a time. `/Om-Oss`
+  and `/om-oss` were two pages to the editor and one page to the browser; a
+  Swedish page slugged `en` and the English front page both answered at `/en`
+  and nothing ever said so.
+- Neither knew that a page with no slug in a locale is still served there under
+  its default-locale slug, so an address the site really serves could be claimed
+  twice.
+
+`resolvePathCore` now takes the locale the host derived from the domain, and a
+locale prefix in the path overrides it — the address the visitor typed is the
+address they asked for. Its answer carries the locale it resolved under, so the
+caller renders the language the URL named rather than the one the host guessed.
+Within that locale a slug answers both prefixed and bare, because a locale
+served from its own domain has no prefix to strip; across locales nothing is
+shared.
+
+Stored redirect rows are the exception: they are literal strings an editor
+typed, and they are matched as they were stored. Re-spelling one through the
+route identity would look it up at an address the table does not hold.
+
 ## One rule decides what is public
 
 `src/cms/page-publication.ts` holds it, in a sentence:
@@ -164,42 +199,65 @@ carry a 404 five seconds past the moment a page goes live.
 
 ### The migrations, and the order they go out in
 
-Three files are new since the last published `0.90.0-m7.12` package, so a site
-upgrading from that baseline is missing all three:
+Four files are new since the last published `0.90.0-m7.12` package, so a site
+upgrading from that baseline is missing all four:
 
 | File | Adds | Needed for |
 | --- | --- | --- |
 | `20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql` | restates the `draft` default, records the `pages.status` column semantics at that migration step, and adds two partial `pages` indexes: one on `key` for undeleted status-published rows, one on `status`/`updated_at` for undeleted rows | canonical schema parity |
 | `20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql` | `page_publications`, the backfill, `cms_save_page_version`, `cms_set_page_status`, `cms_schedule_page_reveal` | contract-v2 publication behaviour |
 | `20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql` | reveals and audit metadata inside `cms_save_page_version`, `cms_soft_delete_page`, `cms_restore_page`, `cms_cancel_page_publication`, `cms_schedule_page_version`, and two repair `UPDATE`s | contract-v2 publication behaviour |
-
-The last two are the pair that establishes contract-v2 publication behaviour:
-together they are what `PLATFORM_CONTRACT_VERSION = 2` means. A site declares the
-contract it was built against and `assertPlatformContract` refuses the mismatch
-at startup, rather than letting an editor discover it when a publish fails
-halfway.
-
-All three are listed in `SCHEMA_MIGRATIONS`. `compareSchema` names whichever of
+| `20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql` | `app.cms_lock_pages` and the rewritten bodies of `cms_save_page_version`, `cms_set_page_status`, `cms_schedule_page_reveal`, `cms_schedule_page_version` and `cms_cancel_page_publication` — the same signatures, taking the same locks in the same order — plus `cms_duplicate_page` and the ledger it retries against | contract-v3 publication behaviour |
+
+The last three establish contract-v3 publication behaviour: together they are
+what `PLATFORM_CONTRACT_VERSION = 3` means. A site declares the contract it was
+built against and `assertPlatformContract` refuses the mismatch at startup,
+rather than letting an editor discover it when a publish fails halfway.
+
+The fourth file changes no signature and no decision: every one of the five
+bodies it replaces answers exactly what it answered before. What changes is the
+order in which each one takes its locks. Every page a statement will touch is
+locked first, in `uuid` order, by a single `app.cms_lock_pages` call; only then
+are that page's publication rows locked, by `id`. Two things were wrong before.
+A save that also scheduled a reveal locked its own page and then, still holding
+it, reached for the reveal's target — so two editors saving two pages that point
+at each other could each end up holding what the other was waiting for. And
+`cms_cancel_page_publication` locked the publication before the page, the
+reverse of every sibling. One order, with the page tier taken in one statement,
+is what removes both.
+
+`cms_duplicate_page` is that same rule applied to a copy. Source and destination
+are locked together, the source's blocks are re-identified and written to a new
+draft, and the caller's idempotency key is recorded — one transaction that
+either produces the whole copy or leaves nothing behind. The caller sends a
+digest of the content it read, so a source that moved in between is refused
+rather than quietly copied from something the editor never saw, and a retry
+carrying the same key answers with the copy that already exists instead of
+making a second one.
+
+All four are listed in `SCHEMA_MIGRATIONS`. `compareSchema` names whichever of
 them is missing and does not report in sync until every canonical migration has
 been applied, so applying only the publication pair leaves the drift check
-pointing at the first file.
+pointing at the first file and the fourth.
 
 Release order, and it is not interchangeable:
 
 1. **Apply every missing canonical migration.** Upgrading from `0.90.0-m7.12`,
-   that is all three files above, in chronological order. They add a column
+   that is all four files above, in chronological order. They add a column
    default, indexes and a comment, a table, functions and replaced function
-   bodies, and the running m7.12 package keeps working against them. They are
-   not, however, pure DDL: the second backfills an open publication for every
-   published page that has none, and the third runs two repair `UPDATE`s over
-   rows the old code left inconsistent — retiring publications still open on
-   pages already in the trash, and setting those pages' status back to `draft`.
-   Both are described below. Nothing is deleted and no page that is public
-   before the upgrade stops being public because of it.
-2. **Deploy the contract-v2 package.** It calls the new signatures, which by then
+   bodies, and the running m7.12 package keeps working against them — including
+   the fourth, whose replaced bodies keep both the signatures and the answers
+   that package already expects. They are not, however, pure DDL: the second
+   backfills an open publication for every published page that has none, and the
+   third runs two repair `UPDATE`s over rows the old code left inconsistent —
+   retiring publications still open on pages already in the trash, and setting
+   those pages' status back to `draft`. Both are described below. Nothing is
+   deleted and no page that is public before the upgrade stops being public
+   because of it.
+2. **Deploy the contract-v3 package.** It calls the new signatures, which by then
    exist.
 3. **Verify both.** `compareSchema` reports in sync — no canonical migration
-   missing — and `assertPlatformContract(2)` returns. The second compares two
+   missing — and `assertPlatformContract(3)` returns. The second compares two
    version numbers in the site's own code and never reads the database, so on
    its own it says nothing about whether the migrations ran.
 4. **Let editors back in.**