@caelo-cms/shared 0.10.52 → 0.10.55

package/src/markup-structure.test.ts

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  freeRegions,
+  isPattern,
+  MAX_NODES,
+  moduleRoots,
+  NEAR_MATCH_THRESHOLD,
+  outermostPatterns,
+  parseMarkup,
+  shapeSimilarity,
+  shapeTree,
+  stripMustache,
+  templateShape,
+} from "./markup-structure.js";
+
+const chain = (steps: string[]) =>
+  `<div class="chain">${steps
+    .map((s, i) => `<div class="step"><span class="n">${i + 1}</span><p>${s}</p></div>`)
+    .join('<span class="arrow"></span>')}</div>`;
+
+function shapeOf(html: string) {
+  const root = parseMarkup(html)[0];
+  if (!root) throw new Error("no element");
+  const shape = shapeTree(root).get(root);
+  if (!shape) throw new Error("no shape");
+  return shape;
+}
+
+describe("signatures", () => {
+  it("ignore text and repetition: a 3-step and a 5-step chain are the same pattern", () => {
+    const a = shapeOf(chain(["Crawl", "Diff", "Alert"]));
+    const b = shapeOf(chain(["One", "Two", "Three", "Four", "Five"]));
+    expect(a.signature).toBe(b.signature);
+    expect(isPattern(a)).toBe(true);
+  });
+
+  it("class order and duplicate class tokens do not matter", () => {
+    expect(shapeOf('<div class="b a a"><p></p></div>').signature).toBe(
+      shapeOf('<div class="a b"><p></p></div>').signature,
+    );
+  });
+
+  it("a different class makes a different signature", () => {
+    expect(shapeOf(chain(["x"])).signature).not.toBe(
+      shapeOf(chain(["x"]).replace('class="chain"', 'class="flow"')).signature,
+    );
+  });
+
+  it("near matches score above the threshold, unrelated markup below", () => {
+    const a = shapeOf(chain(["x", "y"]));
+    const b = shapeOf(chain(["x", "y"]).replace("</p>", "</p><small>note</small>"));
+    expect(a.signature).not.toBe(b.signature);
+    expect(shapeSimilarity(a, b)).toBeGreaterThanOrEqual(NEAR_MATCH_THRESHOLD);
+    const c = shapeOf('<table class="pm"><tr><th>a</th><td>b</td></tr></table>');
+    expect(shapeSimilarity(a, c)).toBeLessThan(0.2);
+  });
+});
+
+describe("isPattern", () => {
+  it("class-less prose never qualifies, however deep", () => {
+    expect(isPattern(shapeOf("<ul><li><a>x</a><strong>y</strong></li></ul>"))).toBe(false);
+    expect(isPattern(shapeOf("<table><thead><tr><th>a</th></tr></thead></table>"))).toBe(false);
+  });
+
+  it("small classed markup is not a component", () => {
+    expect(isPattern(shapeOf('<p class="lead"><a>x</a></p>'))).toBe(false);
+  });
+});
+
+describe("outermostPatterns", () => {
+  it("reports the outer pattern, not the patterns inside it", () => {
+    const html = `<section class="wrap"><h2>t</h2>${chain(["a", "b"])}</section>`;
+    const found = outermostPatterns(parseMarkup(html));
+    expect(found.map((f) => f.node.tag + f.node.classes.join("."))).toEqual(["sectionwrap"]);
+  });
+
+  it("finds several patterns side by side in prose", () => {
+    const html = `<p>intro</p>${chain(["a"])}<p>mid</p>${chain(["b"]).replace("chain", "pair")}`;
+    expect(outermostPatterns(parseMarkup(html)).map((f) => f.node.classes[0])).toEqual([
+      "chain",
+      "pair",
+    ]);
+  });
+});
+
+describe("templates and free regions", () => {
+  const template =
+    '<section class="prose"><h2>{{title}}</h2><div class="body">{{body}}</div>' +
+    '<ul class="tags">{{#tags}}<li class="tag">{{.}}</li>{{/tags}}</ul></section>';
+
+  it("stripMustache matches the two-pass regex on edge cases and stays linear on long brace runs", () => {
+    const regex = (t: string): string =>
+      t.replace(/\{\{\{[^}]*\}\}\}/g, "").replace(/\{\{[^}]*\}\}/g, "");
+    for (const t of [
+      "{{x{{{y}}}",
+      "{{a}}}",
+      "{{{a}}",
+      "{{{{a}}}}",
+      "a{b}c{{",
+      "{{}}{{{}}}",
+      "}}{{a}b}}",
+      "<p>{{#s}}{{{h}}}{{/s}}</p>",
+    ]) {
+      expect(stripMustache(t)).toBe(regex(t));
+    }
+    const started = performance.now();
+    stripMustache("{{{{{{".repeat(50_000));
+    stripMustache(`${"{{".repeat(50_000)}}`);
+    expect(performance.now() - started).toBeLessThan(500);
+  });
+
+  it("stripMustache keeps the markup a template renders", () => {
+    expect(stripMustache("<p>{{a}}{{{b}}}</p>{{#s}}<i></i>{{/s}}{{>n}}")).toBe("<p></p><i></i>");
+  });
+
+  it("everything a template renders, list items included, is not free", () => {
+    const rendered = parseMarkup(
+      '<section class="prose" data-caelo-module-id="m1"><h2>Hi</h2><div class="body"><p>text</p></div>' +
+        '<ul class="tags"><li class="tag">a</li><li class="tag">b</li></ul></section>',
+    );
+    const root = moduleRoots(rendered)[0];
+    if (!root) throw new Error("no module root");
+    const free = freeRegions(root, parseMarkup(stripMustache(template)));
+    expect(free?.map((n) => n.tag)).toEqual(["p"]);
+  });
+
+  it("markup pasted into a richtext value is a free region", () => {
+    const rendered = parseMarkup(
+      `<section class="prose" data-caelo-module-id="m1"><h2>Hi</h2><div class="body">${chain(["a", "b"])}</div></section>`,
+    );
+    const root = moduleRoots(rendered)[0];
+    if (!root) throw new Error("no module root");
+    const free = freeRegions(root, parseMarkup(stripMustache(template))) ?? [];
+    expect(outermostPatterns(free).map((f) => f.node.classes[0])).toEqual(["chain"]);
+  });
+
+  it("a nested module is opaque to its parent and found on its own", () => {
+    const rendered = parseMarkup(
+      `<section class="prose" data-caelo-module-id="m1"><div class="body">${chain(["a"]).replace(
+        '<div class="chain"',
+        '<div class="chain" data-caelo-module-id="m2"',
+      )}</div></section>`,
+    );
+    expect(moduleRoots(rendered).map((r) => r.moduleId)).toEqual(["m1", "m2"]);
+    const root = moduleRoots(rendered)[0];
+    if (!root) throw new Error("no module root");
+    expect(freeRegions(root, parseMarkup(stripMustache(template)))).toEqual([]);
+  });
+
+  it("returns null when the rendered root is not the template's root", () => {
+    const rendered = parseMarkup('<nav data-caelo-module-id="m3"><a>x</a></nav>');
+    const root = moduleRoots(rendered)[0];
+    if (!root) throw new Error("no module root");
+    expect(freeRegions(root, parseMarkup(stripMustache(template)))).toBeNull();
+  });
+
+  it("templateShape fingerprints the template's root element", () => {
+    const t = templateShape(
+      '<div class="chain">{{#steps}}<div class="step"><span class="n">{{n}}</span><p>{{t}}</p></div><span class="arrow"></span>{{/steps}}</div>',
+    );
+    expect(t?.signature).toBe(shapeOf(chain(["a", "b", "c"])).signature);
+  });
+});
+
+describe("bounds", () => {
+  it("stops collecting elements at MAX_NODES", () => {
+    const html = "<div>".repeat(10) + "<i></i>".repeat(MAX_NODES + 100) + "</div>".repeat(10);
+    const roots = parseMarkup(html);
+    let count = 0;
+    const walk = (n: (typeof roots)[number]) => {
+      count++;
+      for (const c of n.children) walk(c);
+    };
+    for (const r of roots) walk(r);
+    expect(count).toBe(MAX_NODES);
+  });
+
+  it("does not descend into svg icons", () => {
+    const root = parseMarkup('<span class="i"><svg><g><path/><path/></g></svg></span>')[0];
+    expect(root?.children[0]?.children).toEqual([]);
+  });
+});

package/src/markup-structure.ts

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #820 — structural fingerprints of HTML, for telling "this markup is
+ * a reusable pattern that already exists elsewhere" from one-off content.
+ *
+ * Free HTML (a step chain, a comparison table, a timeline pasted into a
+ * richtext value, or minted as a one-off module per page) is cheap to
+ * write and expensive to keep: every copy is edited separately, the copies
+ * drift, and the pattern's CSS has to live in the layout where it ships on
+ * every page. The fix is to make the second copy a module. This file gives
+ * the write-time guard and the core `structure` quality check one shared
+ * notion of "the same markup":
+ *
+ * - A node's SIGNATURE is its tag plus sorted class tokens plus the
+ *   signatures of its distinct children (first-occurrence order). Text,
+ *   attribute values and repetition are ignored, so a 5-step chain and a
+ *   7-step chain with different copy are the same pattern.
+ * - A subtree QUALIFIES as a pattern when it is big enough to be a
+ *   component (MIN_PATTERN_NODES distinct nodes over MIN_PATTERN_DEPTH
+ *   levels) and carries at least one class. Prose converted from Markdown
+ *   (`<ul><li><a>`, plain tables) has no classes and never qualifies; an
+ *   authored component always has them.
+ * - SIMILARITY is the Jaccard index over parent→child edges, for near
+ *   matches that are not exact (a pattern with one extra element).
+ *
+ * The site importer's boilerplate walker (site-importer/boilerplate.ts)
+ * stays separate on purpose: it streams byte ranges, hashes text into a
+ * content signature, and its signatures are persisted and replayed
+ * (#424), so its output must stay byte-stable.
+ *
+ * Every walk is bounded (MAX_NODES) so an adversarial body cannot blow it up.
+ */
+
+import { Parser } from "htmlparser2";
+
+/** One element of parsed markup. Text is dropped; it never matters here. */
+export interface MarkupNode {
+  readonly tag: string;
+  readonly classes: readonly string[];
+  /** The `data-caelo-module-id` the composer stamps on every module root. */
+  readonly moduleId: string | null;
+  readonly children: MarkupNode[];
+  readonly parent: MarkupNode | null;
+}
+
+/** Most elements one parse keeps; the rest of the document is ignored. */
+export const MAX_NODES = 50_000;
+/** A pattern has at least this many distinct nodes… */
+export const MIN_PATTERN_NODES = 4;
+/** …spread over at least this many levels (root, child, grandchild). */
+export const MIN_PATTERN_DEPTH = 3;
+/** Jaccard similarity at or above which two patterns are "near" matches. */
+export const NEAR_MATCH_THRESHOLD = 0.8;
+
+/** Elements whose inside is not markup structure (icons, raw text). */
+const LEAF_TAGS = new Set(["svg", "math", "script", "style", "noscript", "iframe"]);
+
+/** Parse markup into a forest of element nodes. */
+export function parseMarkup(html: string): MarkupNode[] {
+  const roots: MarkupNode[] = [];
+  const stack: (MarkupNode | null)[] = [];
+  let count = 0;
+  let leafDepth = 0;
+  const parser = new Parser(
+    {
+      onopentag(name, attribs) {
+        if (leafDepth > 0 || count >= MAX_NODES) {
+          stack.push(null);
+          if (leafDepth > 0) leafDepth++;
+          return;
+        }
+        const tag = name.toLowerCase();
+        const parent = findOpen(stack);
+        const node: MarkupNode = {
+          tag,
+          classes: splitClasses(attribs.class),
+          moduleId: attribs["data-caelo-module-id"] ?? null,
+          children: [],
+          parent,
+        };
+        count++;
+        if (parent) parent.children.push(node);
+        else roots.push(node);
+        stack.push(node);
+        if (LEAF_TAGS.has(tag)) leafDepth = 1;
+      },
+      onclosetag() {
+        stack.pop();
+        if (leafDepth > 0) leafDepth--;
+      },
+    },
+    { decodeEntities: true, lowerCaseTags: true },
+  );
+  parser.write(html);
+  parser.end();
+  return roots;
+}
+
+function findOpen(stack: readonly (MarkupNode | null)[]): MarkupNode | null {
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const n = stack[i];
+    if (n) return n;
+  }
+  return null;
+}
+
+function splitClasses(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return [...new Set(raw.split(/\s+/).filter((c) => c.length > 0))].sort();
+}
+
+/**
+ * Remove Mustache tags (`{{x}}`, `{{{x}}}`, `{{#s}}`, `{{/s}}`, `{{>p}}`)
+ * from a module template so it parses as the markup it renders: a section
+ * body stays once, a placeholder becomes empty.
+ */
+export function stripMustache(template: string): string {
+  return stripDelimited(stripDelimited(template, 3), 2);
+}
+
+/**
+ * Removes every `{`×n + non-`}` run + `}`×n span, leftmost first — the
+ * same result as `replace(/\{{n}[^}]*\}{n}/g, "")`, in linear time. The
+ * regex form backtracks quadratically on long `{{{{…` runs in module HTML
+ * (CodeQL js/polynomial-redos); here, when the first `}` after an opener
+ * does not start the closer, no opener before that `}` can match either
+ * (they all hit the same `}`), so the scan resumes there.
+ */
+function stripDelimited(text: string, n: number): string {
+  const opener = "{".repeat(n);
+  const closer = "}".repeat(n);
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const open = text.indexOf(opener, i);
+    if (open < 0) break;
+    const brace = text.indexOf("}", open + n);
+    if (brace < 0) break;
+    if (text.startsWith(closer, brace)) {
+      out += text.slice(i, open);
+      i = brace + n;
+    } else {
+      out += text.slice(i, brace);
+      i = brace;
+    }
+  }
+  return out + text.slice(i);
+}
+
+/** The node's key without its children: `div.card.card--wide`. */
+export function nodeKey(n: Pick<MarkupNode, "tag" | "classes">): string {
+  return n.classes.length === 0 ? n.tag : `${n.tag}.${n.classes.join(".")}`;
+}
+
+/** Structural facts about one subtree. */
+export interface SubtreeShape {
+  /** Repetition- and text-independent structural signature. */
+  readonly signature: string;
+  /** Distinct nodes after repetition collapse. */
+  readonly nodeCount: number;
+  /** Levels, the subtree root counting as 1. */
+  readonly depth: number;
+  /** Whether any node in it carries a class. */
+  readonly hasClass: boolean;
+  /** Parent→child edges, for near-match similarity. */
+  readonly edges: ReadonlySet<string>;
+}
+
+/**
+ * Compute the shapes of a subtree and all its descendants in one pass.
+ * Nested module roots are opaque: their own module owns them.
+ */
+export function shapeTree(root: MarkupNode, out = new Map<MarkupNode, SubtreeShape>()) {
+  const visit = (n: MarkupNode): SubtreeShape => {
+    const seen = new Set<string>();
+    const parts: string[] = [];
+    let nodeCount = 1;
+    let depth = 1;
+    let hasClass = n.classes.length > 0;
+    const edges = new Set<string>();
+    const key = nodeKey(n);
+    for (const c of n.children) {
+      if (c.moduleId !== null) continue;
+      const s = visit(c);
+      if (seen.has(s.signature)) continue;
+      seen.add(s.signature);
+      parts.push(s.signature);
+      nodeCount += s.nodeCount;
+      depth = Math.max(depth, s.depth + 1);
+      hasClass ||= s.hasClass;
+      edges.add(`${key}>${nodeKey(c)}`);
+      for (const e of s.edges) edges.add(e);
+    }
+    const shape: SubtreeShape = {
+      signature: parts.length === 0 ? key : `${key}(${parts.join(",")})`,
+      nodeCount,
+      depth,
+      hasClass,
+      edges,
+    };
+    out.set(n, shape);
+    return shape;
+  };
+  visit(root);
+  return out;
+}
+
+/** Whether a subtree is big and specific enough to count as a pattern. */
+export function isPattern(shape: SubtreeShape): boolean {
+  return shape.hasClass && shape.nodeCount >= MIN_PATTERN_NODES && shape.depth >= MIN_PATTERN_DEPTH;
+}
+
+/** Jaccard similarity of two shapes' edge sets, 0…1. */
+export function shapeSimilarity(a: SubtreeShape, b: SubtreeShape): number {
+  if (a.signature === b.signature) return 1;
+  let shared = 0;
+  for (const e of a.edges) if (b.edges.has(e)) shared++;
+  const union = a.edges.size + b.edges.size - shared;
+  return union === 0 ? 0 : shared / union;
+}
+
+/** A qualifying pattern found in a piece of markup. */
+export interface FoundPattern {
+  readonly node: MarkupNode;
+  readonly shape: SubtreeShape;
+}
+
+/**
+ * The outermost qualifying patterns in a forest: a pattern inside a bigger
+ * pattern is part of it and not reported on its own.
+ */
+export function outermostPatterns(roots: readonly MarkupNode[]): FoundPattern[] {
+  const found: FoundPattern[] = [];
+  const walk = (n: MarkupNode, shapes: Map<MarkupNode, SubtreeShape>) => {
+    const shape = shapes.get(n);
+    if (shape && isPattern(shape)) {
+      found.push({ node: n, shape });
+      return;
+    }
+    for (const c of n.children) if (c.moduleId === null) walk(c, shapes);
+  };
+  for (const r of roots) walk(r, shapeTree(r));
+  return found;
+}
+
+/** The shape of a whole module template (its first element), or null. */
+export function templateShape(templateHtml: string): SubtreeShape | null {
+  const root = parseMarkup(stripMustache(templateHtml))[0];
+  return root ? (shapeTree(root).get(root) ?? null) : null;
+}
+
+/**
+ * The parts of a rendered module that did NOT come from its template: the
+ * markup field values injected (richtext, text). The rendered tree is
+ * walked in step with the template tree; a rendered child that no template
+ * child can account for (same tag, template's classes all present) starts
+ * a free region. List sections still match, because every iteration of a
+ * section renders the same template child.
+ *
+ * @returns the free region roots, or null when the rendered root does not
+ * match the template root at all (a module the composer renders from
+ * other data, such as a navigation menu) — nothing can be attributed then.
+ */
+export function freeRegions(
+  rendered: MarkupNode,
+  templateRoots: readonly MarkupNode[],
+): MarkupNode[] | null {
+  const tRoot = templateRoots[0];
+  if (!tRoot || !accounts(tRoot, rendered)) return null;
+  const free: MarkupNode[] = [];
+  const walk = (r: MarkupNode, t: MarkupNode) => {
+    for (const c of r.children) {
+      if (c.moduleId !== null) continue;
+      const match = t.children.find((tc) => accounts(tc, c));
+      if (match) walk(c, match);
+      else free.push(c);
+    }
+  };
+  walk(rendered, tRoot);
+  return free;
+}
+
+function accounts(template: MarkupNode, rendered: MarkupNode): boolean {
+  return (
+    template.tag === rendered.tag && template.classes.every((k) => rendered.classes.includes(k))
+  );
+}
+
+/** Every module root (`data-caelo-module-id`) in a forest, nested ones included. */
+export function moduleRoots(roots: readonly MarkupNode[]): MarkupNode[] {
+  const out: MarkupNode[] = [];
+  const walk = (n: MarkupNode) => {
+    if (n.moduleId !== null) out.push(n);
+    for (const c of n.children) walk(c);
+  };
+  for (const r of roots) walk(r);
+  return out;
+}
+
+/** A short operator-readable name for a pattern: its root key, e.g. `div.chain`. */
+export function patternLabel(p: Pick<MarkupNode, "tag" | "classes">): string {
+  return nodeKey(p);
+}

package/src/media.ts

@@ -123,6 +123,49 @@ export function buildMediaUrl(slug: string, variant: MediaVariantTag | string):
     : `${MEDIA_URL_PREFIX}/${slug}/${variant}`;
 }
 
+/**
+ * The favicon rendition of a raster image bound to the theme's favicon
+ * slot: a square PNG, `FAVICON_VARIANT_PX` on each side. Browsers show a
+ * favicon at 16-32 CSS px (64 covers 2x screens). The `orig` of a raster
+ * favicon is often an AI-generated 1024 px PNG of 1-2 MB, and the browser
+ * fetches the `<link rel="icon">` while the page loads: under Lighthouse's
+ * throttled network that download pushed LCP from 0.9 s to 4.7 s on an
+ * otherwise perfect page (real-AI run 39038927234). Created when the
+ * favicon is bound (`themes.set_asset`), not on every upload.
+ */
+export const FAVICON_VARIANT = "icon-64";
+
+/** Edge length in px of {@link FAVICON_VARIANT}. */
+export const FAVICON_VARIANT_PX = 64;
+
+/** Raster mimes: the ones the image pipeline decodes (sharp) and resizes. */
+const RASTER_IMAGE_MIMES: ReadonlySet<string> = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/avif",
+  "image/gif",
+]);
+
+/** Whether `mime` is a raster image the pipeline can decode and resize. */
+export function isRasterImageMime(mime: string): boolean {
+  return RASTER_IMAGE_MIMES.has(mime);
+}
+
+/**
+ * The URL + content type the `<link rel="icon">` of a bound favicon uses.
+ * A raster favicon ships its {@link FAVICON_VARIANT} PNG; ICO and SVG are
+ * favicon formats already and ship as uploaded (`orig`).
+ */
+export function themeFaviconRendition(
+  slug: string,
+  mime: string,
+): { readonly url: string; readonly mime: string } {
+  return isRasterImageMime(mime)
+    ? { url: buildMediaUrl(slug, FAVICON_VARIANT), mime: "image/png" }
+    : { url: buildMediaUrl(slug, "orig"), mime };
+}
+
 /**
  * Turn a human/asset label into a URL-safe media slug: lowercase ascii,
  * kebab-case, extension + junk stripped, capped at 60 chars. NOT

package/src/nested-module-render.ts

@@ -57,6 +57,7 @@
  */
 
 import type { ModuleFieldKind } from "./content.js";
+import { isLinkFailureMarker, type LinkResolver } from "./link-refs.js";
 import { caeloMissingComment, renderTemplate, type TemplateField } from "./template-engine.js";
 
 const MAX_RECURSION_DEPTH = 8;
@@ -158,6 +159,8 @@ interface RenderContext {
    *  module: a switcher can sit inside a nested chrome module. */
   readonly dataLists: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>;
   readonly dormantDataLists: Readonly<Record<string, string>>;
+  /** Epic #724 — resolves internal references in every nested module. */
+  readonly linkResolver: LinkResolver | undefined;
 }
 
 function isNestedRef(v: unknown): v is NestedRefValue {
@@ -193,6 +196,7 @@ export function renderModuleWithContent(
     readonly dataLists: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>;
     readonly dormantDataLists: Readonly<Record<string, string>>;
   },
+  linkResolver?: LinkResolver,
 ): NestedRenderResult {
   const touched = new Set<string>();
   const missing: string[] = [];
@@ -208,6 +212,7 @@ export function renderModuleWithContent(
     themeAssets,
     dataLists: pluginLists?.dataLists ?? {},
     dormantDataLists: pluginLists?.dormantDataLists ?? {},
+    linkResolver,
   });
   return { html, touchedModuleIds: touched, missingSlots: missing, failures };
 }
@@ -255,6 +260,7 @@ function renderInner(moduleId: string, contentInstanceId: string, ctx: RenderCon
     themeAssets: ctx.themeAssets,
     dataLists: ctx.dataLists,
     dormantDataLists: ctx.dormantDataLists,
+    linkResolver: ctx.linkResolver,
   };
 
   return substituteWithRecursion(mod.html, mod.fields, ci.values, childCtx);
@@ -310,8 +316,16 @@ function substituteWithRecursion(
     themeAssets: ctx.themeAssets,
     dataLists: ctx.dataLists,
     dormantDataLists: ctx.dormantDataLists,
+    linkResolver: ctx.linkResolver,
   });
-  for (const m of result.missingSlots) fail(ctx, m);
+  for (const m of result.missingSlots) {
+    // A broken reference inside a nested module stays raw in the partial
+    // HTML (loud-raw), so the enclosing module's render meets it again.
+    // The nested render already reported it with the precise field
+    // trail; drop the echo instead of reporting one broken link twice.
+    if (isLinkFailureMarker(m) && ctx.missing.includes(m)) continue;
+    fail(ctx, m);
+  }
   return result.html;
 }
 
@@ -381,6 +395,8 @@ export function renderPlacedModule(
     readonly themeAssets?: NestedRenderThemeAssets;
     readonly dataLists?: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>;
     readonly dormantDataLists?: Readonly<Record<string, string>>;
+    /** Epic #724 — resolves internal references (see `link-refs.ts`). */
+    readonly linkResolver?: LinkResolver;
   },
 ): NestedRenderResult {
   const touched = new Set<string>();
@@ -400,6 +416,7 @@ export function renderPlacedModule(
     themeAssets: options.themeAssets,
     dataLists: options.dataLists ?? {},
     dormantDataLists: options.dormantDataLists ?? {},
+    linkResolver: options.linkResolver,
   });
   return { html, touchedModuleIds: touched, missingSlots: missing, failures };
 }

package/src/platform-updates.test.ts

@@ -61,6 +61,7 @@ describe("autoInstallRefusal", () => {
     autoSecurity: true,
     autoPatch: false,
     autoMinor: false,
+    autoConverge: false,
     channel: "stable",
     windowStart: null,
     windowEnd: null,
@@ -123,6 +124,7 @@ describe("updatePolicySchema", () => {
     autoSecurity: true,
     autoPatch: false,
     autoMinor: false,
+    autoConverge: false,
     channel: "stable",
     windowStart: "02:00",
     windowEnd: "04:00",
@@ -140,6 +142,9 @@ describe("updatePolicySchema", () => {
       { ...base, soakHours: 1000 },
       { ...base, securitySoakHours: 48 },
       { ...base, extra: true },
+      // "Don't tell me" is gone (#862): security releases are always announced.
+      { ...base, mode: "off" },
+      { ...base, autoConverge: undefined },
     ]) {
       expect(updatePolicySchema.safeParse(bad).success).toBe(false);
     }

package/src/platform-updates.ts

@@ -128,8 +128,12 @@ function comparePrerelease(x: string, y: string): number {
   return 0;
 }
 
-/** The automatic-update modes. */
-export const UPDATE_POLICY_MODES = ["off", "notify", "auto"] as const;
+/**
+ * The automatic-update modes. There is no "off": security releases are
+ * always announced (maintainer decision on #862; migration 0301 moved
+ * stored `off` rows to `notify`).
+ */
+export const UPDATE_POLICY_MODES = ["notify", "auto"] as const;
 export type UpdatePolicyMode = (typeof UPDATE_POLICY_MODES)[number];
 
 /** Release channels a policy may follow (only `stable` installs automatically). */
@@ -158,6 +162,13 @@ export const updatePolicySchema = z
     autoSecurity: z.boolean(),
     autoPatch: z.boolean(),
     autoMinor: z.boolean(),
+    /**
+     * Releases that change the install's Google Cloud project (an
+     * infrastructure-contract bump) may install on their own. Stored and
+     * shown, but inert until those releases can run from Caelo (#819): the
+     * scheduler treats them as notify-only regardless (auto-update.ts).
+     */
+    autoConverge: z.boolean(),
     channel: z.enum(UPDATE_POLICY_CHANNELS),
     /** `HH:MM` local time in `windowTimezone`, or null with windowEnd null = any time. */
     windowStart: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),