@bygghammar/cms-platform 0.91.0 → 0.92.0

package/docs/PUBLICATION-REVIEW.md

@@ -0,0 +1,298 @@
+# Publication review: what the contract v3 upgrade would change
+
+Upgrading a site from 0.90.0-m7.12 to contract v3 changes which publication row
+a page is served from. For most pages that changes nothing. For a few it is the
+difference between a live page and a 404, and the database does not hold enough
+to say which was intended. This is the procedure for asking somebody.
+
+Run it against the site you are about to upgrade, before you apply the
+migration. It reads; it does not write anything to the database.
+
+## Why there is a review at all
+
+Both readers answer the same question — *which version of this page is public
+right now?* — and they disagree about the order of two steps.
+
+| Reader | How it picks |
+| --- | --- |
+| 0.90.0-m7.12 | Drops closed publication rows, then takes the newest of what is left |
+| Contract v3 | Takes the newest row that has started, then asks whether it is still open |
+
+Where a page's newest row has expired and an older one is still open, the old
+reader skipped the expired row and served the open one. The new reader picks the
+expired row first, finds it closed, and serves nothing. The page goes dark on
+deploy, with no error anywhere: the row it should have used is still sitting
+there, one place further down the list.
+
+The new order is the correct one — it is what makes a scheduled window mean what
+it says — so the fix is not to keep the old reader. It is to find the pages this
+reordering moves, repair the ones that can be repaired from the data, and get an
+answer for the rest.
+
+## The shape of a run
+
+```
+export CMS_REVIEW_DSN=postgres://…       # the site you are upgrading
+cms-review scan                          # what is here, and what it would become
+cms-review resolve <page-key> <answer> --by you@example.com
+cms-review approve --site-key voyara --environment production \
+                   --release-sha "$GITHUB_SHA" --by you@example.com \
+                   --confirm-environment production
+PGOPTIONS="$(cms-review options)" psql -f 20260905120000_….sql
+# — or, where the database is on a VPS and nobody types psql:
+cms-review record > migration.approval
+```
+
+`scan` writes `.cms-review.json` in the working directory — `--file` puts it
+somewhere else, and every later subcommand takes the same flag. `show` reprints
+the last scan without touching the database, which is the one to use when
+somebody asks what is still outstanding.
+
+The file is the unit of work. It is worth committing to the deployment's own
+repository, because it is the record of who said what about which page.
+
+## What the scan calls things
+
+Seven classifications, evaluated in order and mutually exclusive. Three of them
+stop the upgrade until a person answers.
+
+| Classification | What it means | Needs an answer |
+| --- | --- | --- |
+| `already_safe` | Both readers serve the same version | no |
+| `hidden_by_design` | The page is not published, so it was never public | no |
+| `hidden_by_expiry` | Every window had already closed; it was already dark | no |
+| `preserved` | An expired row shadows an open one — the migration repairs this | no |
+| `structurally_invalid` | The publication rows contradict themselves | **yes** |
+| `disagreement` | The two readers serve *different versions* of this page | **yes** |
+| `needs_review` | One database state, two opposite intentions | **yes** |
+
+`preserved` is the case the upgrade was written for, and it is settled without
+asking: today's public appearance is kept. The scan lists those pages anyway, so
+that "the migration is about to touch these" is never a surprise.
+
+`needs_review` covers the two shapes nobody can decide from the outside. A page
+whose only window has not opened yet is either meant to stay live until it does
+or meant to go dark now, and the rows are identical in both cases. A page whose
+windows are in an ambiguous order has the same problem one level down.
+
+## The three answers
+
+| Answer | What it does |
+| --- | --- |
+| `publish-legacy-version` | Write a fresh open publication row for the version the old reader served |
+| `leave-hidden` | Accept that the page goes dark |
+| `no-change` | Touch nothing; the new reader's answer is the right one |
+
+`publish-legacy-version` is offered only where it is honest. If the version the
+old reader served belongs to a different page, the scan does not list it as an
+available answer and the migration refuses it — writing another page's content
+into this page's publication row under a note claiming preservation is not
+preservation.
+
+Record one with `--note` when the reason will not be obvious in six months. The
+note travels into the approval and into the audit row the migration writes.
+
+## The connection string is never an argument
+
+The database comes from `CMS_REVIEW_DSN`, or from `DATABASE_URL`. There is no
+`--dsn` flag and there will not be one: an argument is visible in every `ps` on
+the machine for as long as the process runs, and a connection string usually
+carries a password. The URL is taken apart into `PGHOST`, `PGUSER`, `PGPASSWORD`
+and the rest, which are passed to `psql` in its environment.
+
+A role with `SELECT` on `pages`, `page_versions` and `page_publications` is
+enough for the whole procedure. Nothing here writes to the database.
+
+## What an approval binds itself to
+
+`approve` seals the answers. It refuses while any page still needs one, so the
+migration's own refusal is never the first time you hear about it.
+
+| Flag | |
+| --- | --- |
+| `--by` | Required. Who approved; recorded in the audit row |
+| `--site-key`, `--environment`, `--release-sha` | Required. Which deployment this speaks for |
+| `--confirm-environment` | Required, and must repeat `--environment` exactly |
+| `--expires-in` | Seconds, 60–86400, default 3600 |
+| `--manifest-digest` | Optional; overrides the catalog digest it would compute |
+
+Before it seals anything, `approve` prints the site, the environment, the
+database identity, the host it would connect to and how many pages were
+answered, and then refuses unless `--confirm-environment` repeats the
+environment back. That is deliberate friction. It is the last point at which
+`production` typed in a staging terminal is still recoverable. If
+`CMS_ENVIRONMENT` is set and disagrees with `--environment`, it stops there
+instead — one of the two is wrong and neither the CLI nor the migration can tell
+which.
+
+The sealed approval carries a digest of the migration file's bytes, a digest of
+the whole catalog of migrations this package ships, a fingerprint of the rows
+the scan read, and the moment it was evaluated. The migration recomputes all of
+it. An approval is therefore good for one database, one release, one package,
+one `.sql` file and one hour — and for the rows as they stood when they were
+read. Edit the migration after approving it and the approval stops matching.
+
+`approve` also checks this package's migration manifest against its own
+`migrations/` directory, because it is holding both. In a checkout a mismatch
+means somebody edited a `.sql` without running `npm run manifest`. In an
+installed package it means something worse, since publishing checks the same
+thing.
+
+## Handing it to the migration
+
+There are two roads an approval can travel, and both are rendered from the same
+builder inside `cms-review`, so they cannot say different things about the same
+review.
+
+### The road with a psql prompt
+
+`options` prints the sealed approval as PostgreSQL startup options:
+
+```
+PGOPTIONS="$(cms-review options)" psql -f 20260905120000_….sql
+```
+
+Fourteen of those settings are required — `approval_nonce`, `site_key`,
+`environment`, `review_database_identity`, `release_sha`, `package_version`,
+`migration_name`, `migration_digest`, `run_id`, `input_fingerprint`,
+`manifest_digest`, `decision_count`, `approval_expires_at`, `evaluated_at` —
+each read as `lovable.<name>`, with absent and empty treated the same way. The
+answers themselves travel alongside them, as `lovable.decisions`, and so do the
+two people, as `lovable.classified_by_email` and `lovable.approved_by_email`.
+
+### The road with no psql prompt
+
+On a self-hosted VPS nobody types `psql`. The approval is carried there as a
+file, installed by the deployment tooling, and read back by a shell function
+that never runs any of this JavaScript. `cms-review record` prints exactly that
+file:
+
+```
+cms-review record > migration.approval
+scp migration.approval you@vps:
+```
+
+The record is nineteen `key=value` lines in a fixed order, one line each,
+newline-terminated:
+
+| # | Key | |
+| --- | --- | --- |
+| 1 | `approval_nonce` | 32 lowercase hex characters; this approval, spent once |
+| 2 | `site_key` | Which site |
+| 3 | `environment` | `staging` or `production` |
+| 4 | `database_identity` | The **cluster**: `system_identifier` from `pg_control_system()` |
+| 5 | `review_database_identity` | The **database**: `current_database()` and its oid |
+| 6 | `release_sha` | The commit this speaks for |
+| 7 | `package_version` | The package that produced it |
+| 8 | `migration_name` | With its `.sql` suffix |
+| 9 | `migration_digest` | sha256 of the migration's bytes |
+| 10 | `run_id` | The scan this approval descends from |
+| 11 | `input_fingerprint` | The rows as they stood when read |
+| 12 | `manifest_digest` | The whole catalog of migrations |
+| 13 | `decision_count` | How many answers, as a decimal |
+| 14 | `decisions` | Canonical JSON — sorted keys, no spaces |
+| 15 | `decisions_digest` | sha256 of exactly the text on line 14 |
+| 16 | `evaluated_at` | UTC, whole seconds, ending `Z` |
+| 17 | `approval_expires_at` | UTC, whole seconds, ending `Z` |
+| 18 | `classified_by_email` | Who answered the pages |
+| 19 | `approved_by_email` | Who approved the answers |
+
+`record` refuses harder than `options` does, on purpose. It requires
+`staging` or `production` rather than any environment string, and it checks
+every field's shape — the nonce is hex, the digests are forty hex characters,
+the timestamps are whole seconds, an address is at most 254 characters counted
+whole, `@` and domain included, nothing is outside printable ASCII — before it
+prints anything. Each of those is the reader's own bound, counted the way the
+reader counts it, so that what this command prints is what a server accepts. The connection road would let some of those through and let the
+migration decide. The record road cannot: by the time the file is read, you are
+not at the keyboard, so the refusal has to happen while you still are.
+
+### Two identities, and why the record carries both
+
+`database_identity` names the **cluster**. It is what the deployment tooling
+asks about, because that side is deciding whether this approval belongs to the
+machine it is standing on. `review_database_identity` names the **database**,
+which is what the review actually read and what the migration checks, because a
+cluster can hold more than one and only one of them was scanned. Neither is a
+substitute for the other, and the record carries both rather than making one
+side reinterpret a field that means something else to whoever wrote it.
+
+The run the migration writes keeps the sharper of the two, in
+`cms_publication_review_runs.review_database_identity`. The cluster identifier
+has already done its work by then — the deployment tooling checked it before it
+opened a connection — and a second copy of a settled answer is something to
+drift rather than something to check against. The column is named for the
+setting it came from, so a run found in a backup months later does not have to
+be guessed at.
+
+### Two people, and why the record carries both
+
+An approval is two acts. Somebody classified the pages, and somebody approved
+the classification. Today `cms-review` records the same address for both,
+because one person did both; the record still carries two fields, so a
+four-eyes procedure does not need a new record format, and so the migration's
+audit row can name a person rather than recording the change as unattended.
+Where the two agree, `install-lovable-migration-approval` prints one line; where
+they differ, it prints both.
+
+### Zero answers, written down
+
+An approval with nothing to answer is expressible, and it is not the same thing
+as no approval. `decision_count` is `0`, `decisions` is `[]`, and
+`decisions_digest` is the sha256 of those two bytes — the same value the shell
+computes with `sha256sum` and the same one PostgreSQL computes over the `jsonb`,
+because the CLI emits canonical JSON rather than whatever key order it happened
+to build the object in. That is what records a deliberate approval of a run the
+scan would have been content to make on its own.
+
+### Two limits worth knowing before you plan a large review
+
+No value may contain a space. The server splits `PGOPTIONS` on whitespace, so a
+note with a space in it arrives as a separate unparseable argument and the
+connection fails saying nothing about notes. `cms-review` rejects the space
+where you typed it instead.
+
+The whole string must fit in the startup packet, which is a little under 10000
+bytes. `options` refuses above 9000 rather than let the connection fail on the
+far side with no cause named, and `record` refuses above 8192 for the same
+reason one step earlier, since the deployment tooling composes the same options
+from the file. A site with more answered pages than that fits should be answered
+in smaller groups, or have some of the pages resolved in the backoffice before
+the upgrade.
+
+### Proving the two ends still agree
+
+The record is consumed by a shell function in another repository, which is the
+kind of seam that drifts without anyone noticing. `ops/approval-record-roundtrip.mjs`
+runs the real CLI against a real PostgreSQL, hands the file it produced to that
+repository's real reader, and applies the real migration with the options that
+reader composed:
+
+```
+CMS_ROUNDTRIP_TEMPLATE=../lovable-selfhost-deployment-template bun run test:roundtrip
+```
+
+It needs Docker and a checkout of the deployment template, so it is a release
+gate rather than a unit test: it is named in `package.json` as
+`test:roundtrip`, it is step 3 of the release process in
+[CONTRIBUTING.md](../CONTRIBUTING.md), and it is deliberately outside
+`bun run check`, which has to run anywhere. The checkout is an argument or
+`CMS_ROUNDTRIP_TEMPLATE`, never a fixed path. Run it whenever either side of
+the record changes — a change made on one side only is invisible to both
+repositories' CI and fatal on a server.
+
+## Running it without an approval
+
+Most sites never need any of the above. The migration counts the pages that
+require an answer before it does anything else, and if there are none this is an
+ordinary schema change applied as one: the `preserved` pages are repaired, the
+rest are already correct, and no approval is asked for.
+
+If there is even one page that needs an answer and no approval was supplied, the
+migration stops and names the settings it did not get. It does not defer those
+pages to a later run and it does not pick for you — a page going dark and a page
+staying live are both defensible, and which one is right is not in the database.
+
+An approval is honoured even when the scan would have been content to proceed
+alone, which is the way to record the case the count cannot see: a page the
+default would have kept alive that somebody has decided should stay dark.