@bygghammar/cms-platform 0.91.1 → 0.92.0

package/src/platform/publication-review.ts

@@ -0,0 +1,413 @@
+/**
+ * What the upgrade would do to every page, decided once and written down.
+ *
+ * Between 0.90.0-m7.12 and 0.91.1 the rule for "which version does a visitor
+ * see" changed, and the change was not additive. The old reader was:
+ *
+ *   take the newest active publication row whose window is open —
+ *   ORDER BY publish_at DESC LIMIT 1 — and if there is none, fall back to
+ *   pages.current_version_id.
+ *
+ * The new one drops that fallback and adds a published_at tie-break. For most
+ * pages the two agree and nothing happens. For a page that was published by
+ * the old direct-pointer path and never got a publication row, the old reader
+ * served it and the new one serves nothing at all: the page goes dark, quietly,
+ * at the moment of upgrade, and the first anyone hears of it is a visitor.
+ *
+ * This module works out which pages those are before the upgrade rather than
+ * after. It takes the rows as they stand and answers, for each page, what each
+ * reader would serve and what that difference means. Seven answers, four of
+ * which are "nothing to do here" and three of which are somebody's decision:
+ *
+ *   already_safe          both readers serve the same version
+ *   preserved             the old reader served a publication row; it survives
+ *   hidden_by_expiry      it stopped being public before the upgrade, on time
+ *   hidden_by_design      it is not a published page and was never public
+ *   disagreement          both serve something, and they differ            ← decide
+ *   needs_review          which version was served is not knowable          ← decide
+ *   structurally_invalid  the rows contradict themselves                    ← decide
+ *
+ * The distinction that earns its keep is `preserved` against `hidden_by_expiry`.
+ * Both describe a page the new reader will not serve. In the first case that is
+ * an accident of the dropped fallback and the page was live yesterday; in the
+ * second the page's own unpublish_at had already passed and it was *already*
+ * dark. Collapsing them would either hide pages that should stay up or resurrect
+ * pages somebody deliberately retired.
+ *
+ * The same seven answers are computed a second time in SQL, inside the contract
+ * v3 migration, because the migration cannot call this code. `canonicalInputs`
+ * exists so the two can be compared: both sides digest the same shape, and a
+ * pinned corpus proves they agree case by case.
+ */
+
+// Spelled with the extension, which the rest of `src/` does not do, because
+// `scripts/cms-review.mjs` imports this module under a plain node: node strips
+// the types but does not resolve an extensionless specifier, so dropping the
+// `.ts` here to match the surrounding convention stops the CLI from starting.
+import { canonicalJson, type DigestValue } from "./digest.ts";
+
+/** One active publication row, as both readers see it. */
+export type ReviewPublicationRow = {
+  id: string;
+  versionId: string | null;
+  publishAt: string | null;
+  unpublishAt: string | null;
+  publishedAt: string | null;
+};
+
+/** One page and the rows that decide what it serves. */
+export type ReviewPageInput = {
+  pageId: string;
+  pageKey: string;
+  status: string;
+  currentVersionId: string | null;
+  /** Active rows only. Inactive rows are invisible to both readers. */
+  publications: readonly ReviewPublicationRow[];
+};
+
+export const REVIEW_CLASSIFICATIONS = [
+  "structurally_invalid",
+  "already_safe",
+  "disagreement",
+  "hidden_by_design",
+  "hidden_by_expiry",
+  "preserved",
+  "needs_review",
+] as const;
+
+export type ReviewClassification = (typeof REVIEW_CLASSIFICATIONS)[number];
+
+/** The three that a person has to answer before the upgrade may proceed. */
+const DECISION_REQUIRED: ReadonlySet<ReviewClassification> = new Set([
+  "structurally_invalid",
+  "disagreement",
+  "needs_review",
+]);
+
+export const REVIEW_DECISIONS = ["publish-legacy-version", "leave-hidden", "no-change"] as const;
+
+export type ReviewDecision = (typeof REVIEW_DECISIONS)[number];
+
+/** What the scan worked out about one page. */
+export type ReviewItem = {
+  pageId: string;
+  pageKey: string;
+  classification: ReviewClassification;
+  requiresDecision: boolean;
+  /** What 0.90.0-m7.12 would serve. */
+  legacyVersionId: string | null;
+  /** What 0.91.1 would serve. */
+  v2VersionId: string | null;
+  /** True when the legacy answer came from a row, false when from the fallback. */
+  legacyFromPublication: boolean;
+  governingPublicationId: string | null;
+  scheduledVersionId: string | null;
+  scheduledPublishAt: string | null;
+  ambiguousOrder: boolean;
+  reason: string | null;
+};
+
+/**
+ * The statuses a page may hold, taken from the domain `cms_set_page_status`
+ * enforces. `pages.status` carries no CHECK constraint, so a direct UPDATE can
+ * put anything at all in it — which is why "outside its domain" is one of the
+ * structural faults rather than an impossibility.
+ */
+const PAGE_STATUSES: ReadonlySet<string> = new Set(["draft", "published"]);
+
+/**
+ * Times arrive as strings and are compared as instants. A row whose timestamp
+ * does not parse is not "far in the future", it is broken, and saying so is the
+ * whole point of `structurally_invalid`.
+ */
+function instant(value: string | null): number | null {
+  if (value === null) return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+type Prepared = {
+  row: ReviewPublicationRow;
+  publishAt: number;
+  unpublishAt: number | null;
+  publishedAt: number | null;
+};
+
+/**
+ * Everything wrong with a page's rows, in one pass, so the reason can say which
+ * of several problems was found rather than only the first.
+ */
+function structuralFaults(page: ReviewPageInput, versionOwners: ReadonlyMap<string, string>): string[] {
+  const faults: string[] = [];
+
+  if (!PAGE_STATUSES.has(page.status)) {
+    faults.push(`page status ${JSON.stringify(page.status)} is not one this schema defines`);
+  }
+
+  const owns = (versionId: string): boolean | null => {
+    const owner = versionOwners.get(versionId);
+    if (owner === undefined) return null;
+    return owner === page.pageId;
+  };
+
+  if (page.currentVersionId !== null) {
+    const owned = owns(page.currentVersionId);
+    if (owned === null) faults.push("current_version_id points at a version that does not exist");
+    else if (!owned) faults.push("current_version_id points at another page's version");
+  }
+
+  for (const row of page.publications) {
+    if (row.versionId === null) {
+      faults.push(`publication ${row.id} names no version`);
+    } else {
+      const owned = owns(row.versionId);
+      if (owned === null) faults.push(`publication ${row.id} points at a version that does not exist`);
+      else if (!owned) faults.push(`publication ${row.id} points at another page's version`);
+    }
+
+    const publishAt = instant(row.publishAt);
+    if (publishAt === null) {
+      faults.push(`publication ${row.id} has no usable publish_at`);
+      continue;
+    }
+    const unpublishAt = instant(row.unpublishAt);
+    if (row.unpublishAt !== null && unpublishAt === null) {
+      faults.push(`publication ${row.id} has an unreadable unpublish_at`);
+    } else if (unpublishAt !== null && unpublishAt <= publishAt) {
+      faults.push(`publication ${row.id} is scheduled to end before it starts`);
+    }
+  }
+
+  return faults;
+}
+
+/**
+ * The 0.90.0-m7.12 reader, reproduced.
+ *
+ *   .eq("is_active", true).lte("publish_at", now)
+ *   .or("unpublish_at.is.null,unpublish_at.gt." + now)
+ *   .order("publish_at", { ascending: false }).limit(1)
+ *   versionId = pub?.version_id ?? page.current_version_id
+ *
+ * Closed rows are filtered out *before* the newest is chosen, and a page with
+ * nothing left falls back to its current version pointer.
+ *
+ * `limit(1)` on a tie takes whichever row PostgreSQL reached first, which is
+ * physical order — not something a second implementation can reproduce, and not
+ * something anybody can read back. So the tie is broken by row id instead. That
+ * is not a claim about which row the old reader served: `isAmbiguous` reports
+ * the tie, and a page in that state is never resolved automatically. It only
+ * makes the *record* of the scan reproducible, which it must be, because the
+ * record is digested and a person signs the digest.
+ */
+function legacyAnswer(open: readonly Prepared[]): Prepared | null {
+  let best: Prepared | null = null;
+  for (const candidate of open) {
+    if (best === null || candidate.publishAt > best.publishAt) best = candidate;
+    else if (candidate.publishAt === best.publishAt && candidate.row.id < best.row.id) best = candidate;
+  }
+  return best;
+}
+
+/**
+ * The 0.91.1 reader, reproduced — and the order of its two steps is the whole
+ * difference.
+ *
+ * `governingPublication` picks the newest *started* row by (publish_at,
+ * published_at) without looking at unpublish_at at all; `publicVersionId` then
+ * asks whether that one row is still open, and serves nothing if it is not.
+ *
+ * So a newer row that has already expired does not step aside for an older one
+ * that is still open — it shadows it, and the page goes dark. Under 0.90 the
+ * expired row was filtered out first and the older row served the page as
+ * normal. That single inversion is what `preserved` is about, and it is why
+ * this cannot be written as "the same query with a tie-break".
+ */
+function v2Answer(started: readonly Prepared[], at: number): Prepared | null {
+  let best: Prepared | null = null;
+  for (const candidate of started) {
+    if (best === null) {
+      best = candidate;
+      continue;
+    }
+    if (candidate.publishAt > best.publishAt) best = candidate;
+    else if (candidate.publishAt === best.publishAt) {
+      const a = candidate.publishedAt ?? Number.NEGATIVE_INFINITY;
+      const b = best.publishedAt ?? Number.NEGATIVE_INFINITY;
+      // Row id settles a full tie for the same reason it does above: to make
+      // the record reproducible, not to assert which row won in production.
+      if (a > b || (a === b && candidate.row.id < best.row.id)) best = candidate;
+    }
+  }
+  if (best === null) return null;
+  return best.unpublishAt === null || best.unpublishAt > at ? best : null;
+}
+
+/**
+ * True when the served version was never a function of the data alone.
+ *
+ * Two independent ways to lose determinism, one per reader. The old one breaks
+ * a publish_at tie among open rows by physical row order, which is not a
+ * property anybody can read back. The new one breaks it among started rows by
+ * published_at, which ties or is null often enough to leave the same hole. A
+ * page in either state has no "version it used to serve" to preserve, so it is
+ * never resolved automatically, whatever else is true of it.
+ */
+function isAmbiguous(open: readonly Prepared[], started: readonly Prepared[]): boolean {
+  const latestOf = (rows: readonly Prepared[]): number | null =>
+    rows.reduce<number | null>((max, row) => (max === null || row.publishAt > max ? row.publishAt : max), null);
+
+  const latestOpen = latestOf(open);
+  if (latestOpen !== null && open.filter((row) => row.publishAt === latestOpen).length > 1) {
+    return true;
+  }
+
+  const latestStarted = latestOf(started);
+  if (latestStarted === null) return false;
+  const tied = started.filter((row) => row.publishAt === latestStarted);
+  if (tied.length < 2) return false;
+  if (tied.some((row) => row.publishedAt === null)) return true;
+  return new Set(tied.map((row) => row.publishedAt)).size < tied.length;
+}
+
+/**
+ * Classify one page.
+ *
+ * `versionOwners` maps version id to the page that owns it, which is what makes
+ * "this row points at another page's version" answerable — the single most
+ * confusing shape to inherit, because both readers happily serve it.
+ */
+export function classifyPage(
+  page: ReviewPageInput,
+  now: Date,
+  versionOwners: ReadonlyMap<string, string>,
+): ReviewItem {
+  const at = now.getTime();
+
+  const faults = structuralFaults(page, versionOwners);
+
+  const prepared: Prepared[] = [];
+  for (const row of page.publications) {
+    const publishAt = instant(row.publishAt);
+    if (publishAt === null) continue;
+    prepared.push({ row, publishAt, unpublishAt: instant(row.unpublishAt), publishedAt: instant(row.publishedAt) });
+  }
+
+  const started = prepared.filter((row) => row.publishAt <= at);
+  const open = started.filter((row) => row.unpublishAt === null || row.unpublishAt > at);
+  const hasStarted = started.length > 0;
+
+  // Provenance and value are settled together, because "which version" and
+  // "where it came from" have to agree even on a page whose rows are broken —
+  // the item records both, and a row naming no version is a fallback in
+  // practice however it got there.
+  const legacyRow = legacyAnswer(open);
+  const legacyFromPublication = legacyRow !== null && legacyRow.row.versionId !== null;
+  const legacyVersionId = legacyFromPublication ? legacyRow.row.versionId : page.currentVersionId;
+
+  const v2Row = v2Answer(started, at);
+  const v2VersionId = v2Row?.row.versionId ?? null;
+
+  const ambiguousOrder = isAmbiguous(open, started);
+
+  // The next window that has not opened yet — shown alongside the item so a
+  // reviewer can see that a page which looks dark today is scheduled to return.
+  const scheduled = prepared
+    .filter((row) => row.publishAt > at)
+    .sort((a, b) => a.publishAt - b.publishAt || (a.row.id < b.row.id ? -1 : 1))[0];
+
+  const base = {
+    pageId: page.pageId,
+    pageKey: page.pageKey,
+    legacyVersionId,
+    v2VersionId,
+    legacyFromPublication,
+    governingPublicationId: legacyRow?.row.id ?? null,
+    scheduledVersionId: scheduled?.row.versionId ?? null,
+    scheduledPublishAt: scheduled?.row.publishAt ?? null,
+    ambiguousOrder,
+  };
+
+  const decide = (classification: ReviewClassification, reason: string | null): ReviewItem => ({
+    ...base,
+    classification,
+    requiresDecision: DECISION_REQUIRED.has(classification),
+    reason,
+  });
+
+  // Evaluated in this order, and mutually exclusive by construction.
+  if (faults.length > 0) return decide("structurally_invalid", faults.join("; "));
+
+  if (legacyVersionId === v2VersionId) {
+    return decide("already_safe", null);
+  }
+
+  if (legacyVersionId !== null && v2VersionId !== null) {
+    return decide("disagreement", "the two readers serve different versions of this page");
+  }
+
+  // Everything below is in scope: the old reader served something, the new one
+  // serves nothing. The only question left is whether that is a loss.
+  if (page.status !== "published") {
+    return decide("hidden_by_design", `the page is ${page.status}, so it was not public either way`);
+  }
+
+  if (ambiguousOrder) {
+    return decide("needs_review", "ambiguous_order");
+  }
+
+  if (hasStarted && !legacyFromPublication) {
+    return decide("hidden_by_expiry", "every publication window for this page had already closed");
+  }
+
+  if (legacyFromPublication) {
+    return decide(
+      "preserved",
+      "an expired publication row shadows the open one, so the new reader serves nothing",
+    );
+  }
+
+  // Two shapes reach here, and telling them apart is most of what a reviewer
+  // needs. Both are one database state carrying two opposite intentions, which
+  // is exactly why neither may be resolved on the operator's behalf.
+  if (scheduled !== undefined) {
+    return decide(
+      "needs_review",
+      "this page's only publication window has not opened yet, and the data cannot say whether it " +
+        "is meant to stay live until then or go dark now",
+    );
+  }
+
+  return decide(
+    "needs_review",
+    "the page has no publication row at all, so what it used to serve cannot be established from the data",
+  );
+}
+
+/**
+ * The shape both sides digest.
+ *
+ * Field names are the SQL column names rather than the TypeScript ones, because
+ * the SQL side is the one that cannot be changed after release, and a mismatch
+ * here is a parity failure rather than a bug in either implementation.
+ */
+export function canonicalInputs(item: ReviewItem): DigestValue {
+  return {
+    ambiguous_order: item.ambiguousOrder,
+    classification: item.classification,
+    governing_publication_id: item.governingPublicationId,
+    legacy_from_publication: item.legacyFromPublication,
+    legacy_version_id: item.legacyVersionId,
+    page_id: item.pageId,
+    page_key: item.pageKey,
+    requires_decision: item.requiresDecision,
+    scheduled_publish_at: item.scheduledPublishAt,
+    scheduled_version_id: item.scheduledVersionId,
+    v2_version_id: item.v2VersionId,
+  };
+}
+
+/** The canonical text of an item's inputs, which is what gets hashed. */
+export function reviewInputsText(item: ReviewItem): string {
+  return canonicalJson(canonicalInputs(item));
+}