@caelo-cms/shared 0.10.55 → 0.10.58

package/src/auto-update.test.ts

@@ -57,6 +57,7 @@ function input(over: Partial<AutoUpdateInput> & { version?: string; publishedHou
     release: { version, publishedAt: hoursAgo(publishedHoursAgo) },
     facts: FACTS,
     upgraderAvailable: true,
+    convergeAvailable: true,
     now: NOW,
     ...rest,
   } satisfies AutoUpdateInput;
@@ -245,10 +246,12 @@ describe("decideAutoUpdate — pause", () => {
 
 describe("decideAutoUpdate — releases that never install automatically", () => {
   const cases: [string, Partial<AutoUpdateInput>, string][] = [
-    ["infra change", { facts: { ...FACTS, infraChange: true } }, "needs_cloud_shell"],
+    // autoConverge is off by default: the Owner installs it (#819).
+    ["infra change", { facts: { ...FACTS, infraChange: true } }, "manual"],
+    ["infra change on a security fix", { facts: { ...SECURITY, infraChange: true } }, "manual"],
     [
-      "infra change on a security fix",
-      { facts: { ...SECURITY, infraChange: true } },
+      "infra change, no converge job on this install",
+      { facts: { ...FACTS, infraChange: true }, convergeAvailable: false },
       "needs_cloud_shell",
     ],
     ["destructive migrations", { facts: { ...FACTS, contractMigrations: true } }, "manual"],
@@ -260,7 +263,7 @@ describe("decideAutoUpdate — releases that never install automatically", () =>
     expect(decideAutoUpdate({ ...input({}), ...over }).action).toBe(action);
   });
 
-  it("auto_converge on still never installs a cloud-setup change before #819 (inert)", () => {
+  it("auto_converge on installs a cloud-setup change through the converge job (#819)", () => {
     const everything = {
       ...POLICY,
       autoSecurity: true,
@@ -274,15 +277,51 @@ describe("decideAutoUpdate — releases that never install automatically", () =>
     ]) {
       for (const version of [VERSIONS.patch, VERSIONS.minor]) {
         const d = decideAutoUpdate(input({ policy: everything, facts, version }));
-        expect(d.action).toBe("needs_cloud_shell");
-        expect(d.reason).toContain("takes effect once Caelo can run them itself");
+        expect(d.action).toBe("install");
+        expect(d.action === "install" && d.route).toBe("converge");
       }
     }
   });
 
-  it("auto_converge off says nothing about the Owner's choice", () => {
+  it("auto_converge only widens WHERE a release may install, never WHICH kinds", () => {
+    const d = decideAutoUpdate(
+      input({
+        policy: { ...POLICY, autoPatch: false, autoSecurity: false, autoConverge: true },
+        facts: { ...FACTS, infraChange: true },
+      }),
+    );
+    expect(d.action).toBe("notify");
+  });
+
+  it("auto_converge still waits for the soak period and never takes destructive migrations", () => {
+    const on = { ...POLICY, autoPatch: true, autoConverge: true };
+    const soaking = decideAutoUpdate(
+      input({ policy: on, facts: { ...FACTS, infraChange: true }, publishedHoursAgo: 1 }),
+    );
+    expect(soaking.action).toBe("wait");
+    expect(soaking.action === "wait" && soaking.route).toBe("converge");
+    const destructive = decideAutoUpdate(
+      input({ policy: on, facts: { ...FACTS, infraChange: true, contractMigrations: true } }),
+    );
+    expect(destructive.action).toBe("manual");
+  });
+
+  it("a converge-route install needs the converge job, not the upgrader", () => {
+    const on = { ...POLICY, autoPatch: true, autoConverge: true };
+    const d = decideAutoUpdate(
+      input({ policy: on, facts: { ...FACTS, infraChange: true }, upgraderAvailable: false }),
+    );
+    expect(d.action).toBe("install");
+    const none = decideAutoUpdate(
+      input({ policy: on, facts: { ...FACTS, infraChange: true }, convergeAvailable: false }),
+    );
+    expect(none.action).toBe("needs_cloud_shell");
+  });
+
+  it("auto_converge off: the Owner installs it from Settings → Updates", () => {
     const d = decideAutoUpdate(input({ facts: { ...FACTS, infraChange: true } }));
-    expect(d.reason).not.toContain("takes effect");
+    expect(d.action).toBe("manual");
+    expect(d.reason).toContain("Settings → Updates");
   });
 
   it("auto_converge does not touch releases without a cloud-setup change", () => {

package/src/auto-update.ts

@@ -25,9 +25,11 @@
  *   2. off the stable channel, or the policy only notifies → notify;
  *   3. major → notify (never automatic before 1.0);
  *   4. release information unreadable → blocked (fails loudly, no guess);
- *   5. changes the cloud setup → needs_cloud_shell (never automatic, even
- *      with `autoConverge` on: that choice is inert until the converge job
- *      runs these releases from Caelo, #819);
+ *   5. changes the cloud setup (#819): with no converge job on this
+ *      install → needs_cloud_shell (the terminal path); with one but
+ *      `autoConverge` off → manual (the Owner installs it from Settings →
+ *      Updates); with `autoConverge` on → on through the rules below, and
+ *      an install it decides goes to the converge job (`route: converge`);
  *   6. destructive database changes → manual (never automatic);
  *   7. the kind is not switched on (security / patch / minor) → notify;
  *   8. no upgrader on this install → blocked;
@@ -39,6 +41,7 @@
 
 import {
   inMaintenanceWindow,
+  type PlatformUpdateRoute,
   type StoredUpdatePolicy,
   type UpdateKind,
   updateKind,
@@ -109,6 +112,11 @@ export interface AutoUpdateInput {
   readonly facts: ReleaseFacts | { readonly unavailable: string };
   /** This install has an upgrader the admin can hand a request to. */
   readonly upgraderAvailable: boolean;
+  /**
+   * This install has a converge job the admin can start (#819): releases
+   * that change the cloud setup can install from Caelo at all.
+   */
+  readonly convergeAvailable: boolean;
   /** Why it has none right now, in plain words (null: none set up at all). */
   readonly upgraderProblem?: string | null;
   readonly now: Date;
@@ -128,6 +136,8 @@ export type AutoUpdateDecision =
       readonly version: string;
       readonly kind: UpdateKind;
       readonly basis: AutoUpdateBasis;
+      /** Which job installs it once the wait is over. */
+      readonly route: PlatformUpdateRoute;
       readonly reason: string;
       /** When it becomes installable; null = until the Owner resumes. */
       readonly until: Date | null;
@@ -139,6 +149,8 @@ export type AutoUpdateDecision =
       readonly version: string;
       readonly kind: UpdateKind;
       readonly basis: AutoUpdateBasis;
+      /** Which job installs it: the upgrader, or the converge job (#819). */
+      readonly route: PlatformUpdateRoute;
       readonly reason: string;
     };
 
@@ -228,20 +240,22 @@ export function decideAutoUpdate(input: AutoUpdateInput): AutoUpdateDecision {
     };
   }
   const facts = input.facts;
-  if (facts.infraChange === true) {
-    // FIXME(issue #819): once the converge job runs these releases from
-    // Caelo, `policy.autoConverge` decides here like autoPatch does below.
-    // Until then the Owner's "install automatically" choice is stored but
-    // has no effect, and the reason says so.
-    const ownerChoice = policy.autoConverge
-      ? " Your setting to install these automatically takes effect once Caelo can run them itself."
-      : "";
+  const converge = facts.infraChange === true;
+  if (converge && !input.convergeAvailable) {
     return {
       action: "needs_cloud_shell",
       ...base,
-      reason: `v${v} changes this install's cloud setup, which the admin may not do. It is never installed automatically: the Owner runs it once with their own account in Cloud Shell.${ownerChoice}`,
+      reason: `v${v} changes this install's cloud setup, and this install has no converge job to do that from Caelo. The Owner installs it once with their own account in Cloud Shell or from the computer they installed from.`,
+    };
+  }
+  if (converge && !policy.autoConverge) {
+    return {
+      action: "manual",
+      ...base,
+      reason: `v${v} changes this install's cloud setup. The update policy does not install those automatically; the Owner installs it from Settings → Updates.`,
     };
   }
+  const route: PlatformUpdateRoute = converge ? "converge" : "app_roll";
   if (facts.contractMigrations) {
     return {
       action: "manual",
@@ -265,7 +279,8 @@ export function decideAutoUpdate(input: AutoUpdateInput): AutoUpdateDecision {
       reason: `v${v} is a ${what}; the update policy does not install those automatically. The Owner installs it.`,
     };
   }
-  if (!input.upgraderAvailable) {
+  // A converge-route install needs the converge job (checked above), not the upgrader.
+  if (!converge && !input.upgraderAvailable) {
     return {
       action: "blocked",
       ...base,
@@ -274,7 +289,7 @@ export function decideAutoUpdate(input: AutoUpdateInput): AutoUpdateDecision {
         : `v${v} could install automatically, but this install has no upgrader the admin can start. Run the upgrade command from Settings → Updates once; it sets the upgrader up.`,
     };
   }
-  const auto = { ...base, basis } as const;
+  const auto = { ...base, basis, route } as const;
   if (isPausedAt(policy, now)) {
     const until = policy.pausedUntil === null ? null : new Date(policy.pausedUntil);
     const who = policy.pausedByOwner ? "by the Owner" : "after a failed automatic install";

package/src/google-oauth.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #914 — the shape of a Google OAuth client and the redirect URI IAP
+ * needs on it. Shared so the admin's server-side validation and the setup
+ * page (which shows IAP's redirect URI as the Owner types the client ID)
+ * use one definition.
+ */
+
+/**
+ * A Google OAuth 2.0 client ID (`<project number>-<random>.apps.googleusercontent.com`).
+ * Same pattern as the `operator_oauth_client` CHECK constraint (migration 0323).
+ */
+export const GOOGLE_OAUTH_CLIENT_ID = /^[0-9]+-[a-z0-9]+\.apps\.googleusercontent\.com$/;
+
+/**
+ * IAP's redirect URI for a custom OAuth client: Google sends a signed-in
+ * visitor back to IAP here, so the client must list it among its authorized
+ * redirect URIs (cloud.google.com/iap/docs/custom-oauth-configuration).
+ *
+ * @example
+ *   iapRedirectUri("123-abc.apps.googleusercontent.com")
+ *   // → "https://iap.googleapis.com/v1/oauth/clientIds/123-abc.apps.googleusercontent.com:handleRedirect"
+ */
+export function iapRedirectUri(clientId: string): string {
+  return `https://iap.googleapis.com/v1/oauth/clientIds/${clientId}:handleRedirect`;
+}

package/src/index.ts

@@ -23,8 +23,10 @@ export * from "./fonts.js";
 export * from "./genesis.js";
 export * from "./genesis-inventory.js";
 export * from "./google-models.js";
+export * from "./google-oauth.js";
 export * from "./image-capabilities.js";
 export * from "./interactions.js";
+export * from "./link-canonicalise.js";
 export * from "./link-refs.js";
 export {
   type LogContext,

package/src/link-canonicalise.test.ts

@@ -0,0 +1,387 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Tier-1 unit tests for write-time link canonicalisation (epic #724,
+ * rollout C): which positions are links, what becomes a reference, what
+ * stays literal, and what is an issue.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  canonicaliseContentValues,
+  canonicaliseFieldDefaults,
+  canonicaliseHtmlLinks,
+  canonicaliseJsonLinks,
+  canonicaliseUrl,
+  collectLinkLiterals,
+  describeLinkIssues,
+  type LinkTargetLookup,
+  linkCanonicaliseRun,
+} from "./link-canonicalise.js";
+
+const ABOUT = "11111111-1111-4111-8111-111111111111";
+const HOME = "22222222-2222-4222-8222-222222222222";
+const GONE = "33333333-3333-4333-8333-333333333333";
+const HERO = "44444444-4444-4444-8444-444444444444";
+
+const lookup: LinkTargetLookup = {
+  pageIdForPath: (p) =>
+    (
+      ({
+        "/": HOME,
+        "/company/about": ABOUT,
+        "/old-about": ABOUT,
+        // Old URLs an import redirected (301) to the page.
+        "/about.html": ABOUT,
+        "/about/index.html": ABOUT,
+      }) as Record<string, string>
+    )[p] ?? null,
+  mediaIdForSlug: (s) => (s === "hero" ? HERO : null),
+  pageExists: (id) => id === ABOUT || id === HOME,
+  mediaExists: (id) => id === HERO,
+  isOwnHost: (h) => h === "example.com",
+};
+
+const run = (grandfathered: string[] = []) =>
+  linkCanonicaliseRun(lookup, { grandfathered: new Set(grandfathered) });
+
+describe("canonicaliseUrl", () => {
+  it("turns internal paths, own-domain URLs and media URLs into references", () => {
+    const r = run();
+    expect(canonicaliseUrl("/company/about", r, "x")).toBe(`caelo:page/${ABOUT}`);
+    expect(canonicaliseUrl("/company/about/#team", r, "x")).toBe(`caelo:page/${ABOUT}#team`);
+    expect(canonicaliseUrl("/company/about?ref=nav", r, "x")).toBe(`caelo:page/${ABOUT}?ref=nav`);
+    expect(canonicaliseUrl("/", r, "x")).toBe(`caelo:page/${HOME}`);
+    expect(canonicaliseUrl("https://example.com/company/about", r, "x")).toBe(
+      `caelo:page/${ABOUT}`,
+    );
+    expect(canonicaliseUrl("/old-about", r, "x")).toBe(`caelo:page/${ABOUT}`);
+    expect(canonicaliseUrl("/_caelo/media/hero", r, "x")).toBe(`caelo:media/${HERO}`);
+    expect(canonicaliseUrl("/_caelo/media/hero/webp-800", r, "x")).toBe(
+      `caelo:media/${HERO}/webp-800`,
+    );
+    expect(canonicaliseUrl(`/_caelo/media/${HERO}/webp-400`, r, "x")).toBe(
+      `caelo:media/${HERO}/webp-400`,
+    );
+    expect(r.issues).toEqual([]);
+  });
+
+  it("leaves external, special and non-page URLs literal", () => {
+    const r = run();
+    for (const v of [
+      "https://other.org/about",
+      "//cdn.example.com/x.js",
+      "mailto:hi@example.com",
+      "tel:+491234",
+      "#pricing",
+      "{{cta_href}}",
+      "/robots.txt",
+      "/sitemap.xml",
+      "/_assets/app.css",
+      "/api/forms/contact",
+      "relative/path",
+      "",
+    ]) {
+      expect(canonicaliseUrl(v, r, "x")).toBe(v);
+    }
+    expect(r.issues).toEqual([]);
+  });
+
+  it("reports unknown paths, unknown media and dangling references", () => {
+    const r = run();
+    expect(canonicaliseUrl("/nope", r, "values.cta_href")).toBe("/nope");
+    expect(canonicaliseUrl("/_caelo/media/missing", r, "html")).toBe("/_caelo/media/missing");
+    expect(canonicaliseUrl(`caelo:page/${GONE}`, r, "items[0].href")).toBe(`caelo:page/${GONE}`);
+    expect(canonicaliseUrl(`caelo:page/${ABOUT}`, r, "ok")).toBe(`caelo:page/${ABOUT}`);
+    expect(r.issues.map((i) => [i.kind, i.value, i.where])).toEqual([
+      ["unknown-page-path", "/nope", "values.cta_href"],
+      ["unknown-media", "/_caelo/media/missing", "html"],
+      ["dangling-page-ref", `caelo:page/${GONE}`, "items[0].href"],
+    ]);
+  });
+
+  it("resolves file-shaped old URLs a page or redirect answers before treating them as files", () => {
+    const r = run();
+    expect(canonicaliseUrl("/about.html", r, "x")).toBe(`caelo:page/${ABOUT}`);
+    expect(canonicaliseUrl("/about/index.html#team", r, "x")).toBe(`caelo:page/${ABOUT}#team`);
+    expect(r.issues).toEqual([]);
+  });
+
+  it("reports a file path nothing serves (strict) and keeps it literal (report)", () => {
+    const strict = run();
+    expect(canonicaliseUrl("/files/guide.pdf", strict, "html")).toBe("/files/guide.pdf");
+    expect(canonicaliseUrl("/index.php", strict, "html")).toBe("/index.php");
+    expect(strict.issues.map((i) => [i.kind, i.value])).toEqual([
+      ["unknown-file", "/files/guide.pdf"],
+      ["unknown-file", "/index.php"],
+    ]);
+    const report = linkCanonicaliseRun(lookup, { mode: "report" });
+    expect(canonicaliseUrl("/files/guide.pdf", report, "html")).toBe("/files/guide.pdf");
+    expect(report.issues.map((i) => i.kind)).toEqual(["unknown-file"]);
+    expect(describeLinkIssues(strict.issues)).toContain("media library");
+  });
+
+  it("refuses a media link with a query or anchor instead of dropping it", () => {
+    const r = run();
+    expect(canonicaliseUrl("/_caelo/media/hero#page=3", r, "x")).toBe("/_caelo/media/hero#page=3");
+    expect(canonicaliseUrl("/_caelo/media/hero?download=1", r, "y")).toBe(
+      "/_caelo/media/hero?download=1",
+    );
+    expect(r.issues.map((i) => [i.kind, i.where])).toEqual([
+      ["unsupported-link-form", "x"],
+      ["unsupported-link-form", "y"],
+    ]);
+    const report = linkCanonicaliseRun(lookup, { mode: "report" });
+    expect(canonicaliseUrl("/_caelo/media/hero#page=3", report, "x")).toBe(
+      "/_caelo/media/hero#page=3",
+    );
+    expect(report.issues.map((i) => i.kind)).toEqual(["unsupported-link-form"]);
+  });
+
+  it("stores the orig variant as the plain media reference", () => {
+    const r = run();
+    expect(canonicaliseUrl("/_caelo/media/hero/orig", r, "x")).toBe(`caelo:media/${HERO}`);
+    expect(canonicaliseUrl(`/_caelo/media/${HERO}/orig`, r, "x")).toBe(`caelo:media/${HERO}`);
+    expect(r.issues).toEqual([]);
+  });
+
+  it("grandfathers links already stored", () => {
+    const r = run(["/nope", `caelo:page/${GONE}`]);
+    canonicaliseUrl("/nope", r, "x");
+    canonicaliseUrl(`caelo:page/${GONE}`, r, "x");
+    expect(r.issues).toEqual([]);
+  });
+
+  it("restricts media positions to media", () => {
+    const r = run();
+    expect(canonicaliseUrl("/company/about", r, "x", "media")).toBe("/company/about");
+    expect(r.issues).toEqual([]);
+  });
+
+  it("keeps a link to a planned page literal and pending, never an issue", () => {
+    const planned = new Set(["/later", "/old/page.html"]);
+    const r = linkCanonicaliseRun({ ...lookup, isPendingPagePath: (p) => planned.has(p) });
+    expect(canonicaliseUrl("/later/#x", r, "values.cta_href")).toBe("/later/#x");
+    expect(canonicaliseUrl("https://example.com/old/page.html", r, "html")).toBe(
+      "https://example.com/old/page.html",
+    );
+    // An existing page still resolves; an unplanned path is still an issue.
+    expect(canonicaliseUrl("/company/about", r, "x")).toBe(`caelo:page/${ABOUT}`);
+    expect(canonicaliseUrl("/typo", r, "y")).toBe("/typo");
+    expect(r.pending).toEqual([
+      { value: "/later/#x", path: "/later", where: "values.cta_href" },
+      { value: "https://example.com/old/page.html", path: "/old/page.html", where: "html" },
+    ]);
+    expect(r.issues.map((i) => [i.kind, i.value])).toEqual([["unknown-page-path", "/typo"]]);
+    // Without an import run nothing is pending.
+    const strict = run();
+    canonicaliseUrl("/later", strict, "x");
+    expect(strict.pending).toEqual([]);
+    expect(strict.issues.map((i) => i.kind)).toEqual(["unknown-page-path"]);
+  });
+
+  it("reports a malformed reference instead of passing it through", () => {
+    const r = run();
+    const bad = [
+      "caelo:page/1111", // truncated id
+      `caelo:page/${ABOUT}/team`, // stray path after the id
+      "caelo:page/ABCDEF01-1111-4111-8111-111111111111", // ids are lowercase
+      `caelo:media/${HERO}/WEBP`, // variant outside the grammar
+    ];
+    for (const v of bad) expect(canonicaliseUrl(v, r, "values.cta_href")).toBe(v);
+    expect(r.issues.map((i) => [i.kind, i.value])).toEqual(
+      bad.map((v) => ["malformed-link-ref", v]),
+    );
+    expect(describeLinkIssues(r.issues)).toContain("write the page's path");
+    // Grandfathered like any other stored literal.
+    const g = run(["caelo:page/1111"]);
+    canonicaliseUrl("caelo:page/1111", g, "x");
+    expect(g.issues).toEqual([]);
+  });
+
+  it("turns a query or anchor outside the grammar into an issue, never a throw", () => {
+    // `formatLinkRef` throws on a suffix it cannot parse back; the
+    // canonicaliser must validate with the grammar's own patterns first.
+    const r = run();
+    for (const v of [
+      "/company/about#a b",
+      "/company/about#x#y",
+      "/company/about?a=1?b=2",
+      '/company/about?q="x"',
+      `/company/about#${"a".repeat(257)}`,
+      `/company/about?${"q".repeat(513)}`,
+      "/company/about#über",
+    ]) {
+      expect(() => canonicaliseUrl(v, r, "x")).not.toThrow();
+      expect(canonicaliseUrl(v, run(), "x")).toBe(v);
+    }
+    expect(r.issues.every((i) => i.kind === "unsupported-link-form")).toBe(true);
+    expect(r.issues).toHaveLength(7);
+    // The longest suffixes the grammar allows still become references.
+    const ok = run();
+    const anchor = "a".repeat(256);
+    expect(canonicaliseUrl(`/company/about#${anchor}`, ok, "x")).toBe(
+      `caelo:page/${ABOUT}#${anchor}`,
+    );
+    expect(ok.issues).toEqual([]);
+  });
+});
+
+describe("HTML and JSON positions", () => {
+  it("canonicalises href, src, srcset and poster in HTML", () => {
+    const r = run();
+    const html =
+      `<a class="b" href="/company/about#x">A</a><a href='https://other.org/'>O</a>` +
+      `<img src="/_caelo/media/hero" srcset="/_caelo/media/hero/webp-400 400w, /_caelo/media/hero/webp-800 800w">` +
+      `<img data-src="/company/about" src="/company/about"><a href="{{href}}">t</a>`;
+    expect(canonicaliseHtmlLinks(html, r, "html")).toBe(
+      `<a class="b" href="caelo:page/${ABOUT}#x">A</a><a href='https://other.org/'>O</a>` +
+        `<img src="caelo:media/${HERO}" srcset="caelo:media/${HERO}/webp-400 400w, caelo:media/${HERO}/webp-800 800w">` +
+        `<img data-src="/company/about" src="/company/about"><a href="{{href}}">t</a>`,
+    );
+    expect(r.issues).toEqual([]);
+  });
+
+  it("reads attributes only inside start tags, not in escaped code samples", () => {
+    const r = run();
+    const html =
+      '<pre><code>&lt;a href="/nope"&gt;Docs&lt;/a&gt;</code></pre>' +
+      `<a title="a > b" href="/company/about">x</a><img alt='it"s' src="/_caelo/media/hero">`;
+    expect(canonicaliseHtmlLinks(html, r, "html")).toBe(
+      '<pre><code>&lt;a href="/nope"&gt;Docs&lt;/a&gt;</code></pre>' +
+        `<a title="a > b" href="caelo:page/${ABOUT}">x</a><img alt='it"s' src="caelo:media/${HERO}">`,
+    );
+    expect(r.issues).toEqual([]);
+    // An unterminated quote does not hide the tags before it.
+    expect(canonicaliseHtmlLinks('<a href="/company/about">x</a><b title="oops>', run(), "h")).toBe(
+      `<a href="caelo:page/${ABOUT}">x</a><b title="oops>`,
+    );
+  });
+
+  it("reports malformed references in any HTML link position, once each", () => {
+    const r = run();
+    const html =
+      `<a href="caelo:page/${ABOUT}/team">A</a>` +
+      `<div data-href="caelo:page/1234">B</div>` +
+      `<img srcset="caelo:media/${HERO} 1x, caelo:media/abc 2x">` +
+      `<a href="caelo:page/${ABOUT}#ok">C</a>` +
+      "<p>Write caelo:page/&lt;id&gt; in prose: not a link.</p>";
+    expect(canonicaliseHtmlLinks(html, r, "html")).toBe(html);
+    expect(r.issues.map((i) => [i.kind, i.value])).toEqual([
+      ["malformed-link-ref", `caelo:page/${ABOUT}/team`],
+      ["malformed-link-ref", "caelo:media/abc"],
+      ["malformed-link-ref", "caelo:page/1234"],
+    ]);
+    // HTML without any attribute is still checked (a value that starts
+    // with the broken reference); element text is not a link position.
+    const t = run();
+    canonicaliseHtmlLinks("caelo:page/1234 <b>caelo:page/5678</b>", t, "html");
+    expect(t.issues.map((i) => i.value)).toEqual(["caelo:page/1234"]);
+  });
+
+  it("reports a malformed reference in a plain text value", () => {
+    const r = run();
+    expect(canonicaliseJsonLinks({ label: "caelo:page/1234" }, r, "values")).toEqual({
+      label: "caelo:page/1234",
+    });
+    expect(r.issues.map((i) => [i.kind, i.where])).toEqual([
+      ["malformed-link-ref", "values.label"],
+    ]);
+    // A stored malformed value is grandfathered by the next write.
+    const g = linkCanonicaliseRun(lookup, {
+      grandfathered: collectLinkLiterals({ label: "caelo:page/1234" }),
+    });
+    canonicaliseJsonLinks({ label: "caelo:page/1234" }, g, "values");
+    expect(g.issues).toEqual([]);
+  });
+
+  it("treats link-named keys as URLs and plain text as text", () => {
+    const r = run();
+    const items = [
+      { label: "About", href: "/company/about", children: [{ label: "Home", href: "/" }] },
+      { label: "/month", note: "/month" },
+    ];
+    expect(canonicaliseJsonLinks(items, r, "items")).toEqual([
+      {
+        label: "About",
+        href: `caelo:page/${ABOUT}`,
+        children: [{ label: "Home", href: `caelo:page/${HOME}` }],
+      },
+      { label: "/month", note: "/month" },
+    ]);
+    expect(r.issues).toEqual([]);
+  });
+
+  it("canonicalises content values by field kind and name", () => {
+    const r = run();
+    const out = canonicaliseContentValues(
+      [
+        { name: "cta", kind: "url" },
+        { name: "hero", kind: "image" },
+        { name: "price_suffix", kind: "text" },
+        { name: "nav", kind: "link-list" },
+        { name: "body", kind: "richtext" },
+        { name: "card", kind: "module" },
+      ],
+      {
+        cta: "/company/about",
+        hero: "/_caelo/media/hero",
+        price_suffix: "/month",
+        nav: [{ label: "Home", href: "/" }],
+        body: '<p><a href="/company/about">us</a></p>',
+        card: { moduleId: ABOUT, contentInstanceId: HOME },
+        legacy_href: "/company/about",
+      },
+      r,
+    );
+    expect(out).toEqual({
+      cta: `caelo:page/${ABOUT}`,
+      hero: `caelo:media/${HERO}`,
+      price_suffix: "/month",
+      nav: [{ label: "Home", href: `caelo:page/${HOME}` }],
+      body: `<p><a href="caelo:page/${ABOUT}">us</a></p>`,
+      card: { moduleId: ABOUT, contentInstanceId: HOME },
+      legacy_href: `caelo:page/${ABOUT}`,
+    });
+    expect(r.issues).toEqual([]);
+  });
+
+  it("canonicalises field defaults (layout chrome)", () => {
+    const r = run();
+    const fields = canonicaliseFieldDefaults(
+      [
+        {
+          name: "links",
+          kind: "link-list",
+          label: "L",
+          default: [{ label: "A", href: "/company/about" }],
+        },
+        { name: "title", kind: "text", label: "T", default: "/company/about" },
+      ],
+      r,
+    );
+    expect(fields[0]?.default).toEqual([{ label: "A", href: `caelo:page/${ABOUT}` }]);
+    expect(fields[1]?.default).toBe("/company/about");
+  });
+});
+
+describe("grandfathering + messages", () => {
+  it("collects every link literal from a stored state", () => {
+    const literals = collectLinkLiterals({
+      html: '<a href="/nope">x</a>',
+      values: { cta: "/gone", text: "hello" },
+    });
+    expect(literals.has("/nope")).toBe(true);
+    expect(literals.has("/gone")).toBe(true);
+    expect(literals.has("hello")).toBe(false);
+  });
+
+  it("names the value, the place and the next step", () => {
+    const msg = describeLinkIssues([
+      { kind: "unknown-page-path", value: "/pricing", where: "values.cta_href" },
+    ]);
+    expect(msg).toContain('values.cta_href: "/pricing" is not the path of any page on this site');
+    expect(msg).toContain("list_pages");
+    expect(msg).toContain("create it first");
+  });
+});