@intentius/behold 0.24.0 → 0.26.0

package/web/index.html

@@ -142,6 +142,21 @@
       #ws-gates .ws-gate-title { font-weight: 600; }
       #ws-gates .ws-gate-facts, #ws-gates .ws-gate-note { color: var(--muted); font-size: var(--t-caption); }
       #ws-gates .ws-gate button { margin-top: 4px; }
+      /* #526: SQL Yodeler's report and drift, from files, dated. Never a fill. */
+      #panel-body #tab-yodel.active { display: flex; flex-direction: column; gap: 4px; font-size: var(--t-caption); }
+      #tab-yodel h3 { margin: 8px 0 0; font-size: var(--t-caption); }
+      #tab-yodel .tg-legend { color: var(--muted); overflow-wrap: anywhere; }
+      #tab-yodel .tg-inspect { overflow-wrap: anywhere; }
+      #tab-yodel .tg-refusal { color: var(--degraded); font-weight: 600; }
+      /* #524: SQL Yodeler's gates on chant/lifecycle, dated. A Copy button is the only control. */
+      #panel-body #tab-yodel-lane.active { display: flex; flex-direction: column; gap: 6px; font-size: var(--t-caption); }
+      #tab-yodel-lane h3 { margin: 8px 0 0; font-size: var(--t-caption); }
+      #tab-yodel-lane .tg-legend { color: var(--muted); overflow-wrap: anywhere; }
+      #tab-yodel-lane .tg-refusal { color: var(--degraded); font-weight: 600; }
+      #tab-yodel-lane .ws-gate { border: 1px solid var(--rule); border-radius: 6px; padding: 6px 8px; }
+      #tab-yodel-lane .ws-gate-title { font-weight: 600; }
+      #tab-yodel-lane .ws-gate-facts, #tab-yodel-lane .ws-gate-note { color: var(--muted); overflow-wrap: anywhere; }
+      #tab-yodel-lane .tg-command { display: block; font-family: var(--font-mono); overflow-wrap: anywhere; margin: 4px 0; }
       /* #490: terragucci's reports, dated. Never a fill. */
       #panel-body #tab-terragucci.active { display: flex; flex-direction: column; gap: 8px; font-size: var(--t-caption); }
       #tab-terragucci .tg-legend, #tab-terragucci .tg-estate { color: var(--muted); }
@@ -158,9 +173,51 @@
       #tab-terragucci .tg-cells > span::before { content: attr(data-stage) ": "; color: var(--muted); }
       #tab-terragucci .tg-drift, #tab-terragucci .tg-failed { color: var(--degraded); }
       #tab-terragucci .tg-wave { color: var(--pending); }
+      /* #509: a control repo's projects, over the empty graph area. Dated, never live. */
+      #tg-estate { grid-row: 1; grid-column: 1; z-index: 2; overflow: auto; background: var(--bg); padding: 10px 14px; display: flex; flex-direction: column; gap: 10px; font-size: var(--t-caption); }
+      #tg-estate .tg-estate-head { display: flex; flex-wrap: wrap; gap: 6px 14px; align-items: baseline; }
+      #tg-estate .tg-legend, #tg-estate .tg-none, #tg-estate .ws-gate-facts, #tg-estate .ws-gate-note { color: var(--muted); overflow-wrap: anywhere; }
+      #tg-estate .tg-refusal, #tg-estate .tg-bad { color: var(--degraded); font-weight: 600; }
+      #tg-estate a { color: inherit; }
+      #tg-estate .tg-estate-graph { overflow: auto; }
+      #tg-estate svg text { fill: var(--fg); font-size: 11px; }
+      #tg-estate .tg-project-box { fill: var(--panel); stroke: var(--rule); }
+      #tg-estate .tg-project-box.tg-no-run { stroke-dasharray: 4 3; }
+      #tg-estate .tg-project-name { font-weight: 600; font-size: 12px; }
+      #tg-estate svg .tg-project-counts, #tg-estate svg .tg-project-run.tg-none, #tg-estate svg .tg-wave-label { fill: var(--muted); }
+      #tg-estate svg .tg-project-run.tg-bad { fill: var(--degraded); }
+      #tg-estate svg .tg-wave-waiting, #tg-estate svg .tg-wave-applying { fill: var(--pending); }
+      #tg-estate svg .tg-wave-failed, #tg-estate svg .tg-wave-refused { fill: var(--degraded); }
+      #tg-estate .tg-root-node rect { fill: var(--bg); stroke: var(--edge); }
+      #tg-estate .tg-root-node text { font-family: var(--font-mono); }
+      #tg-estate .tg-edge { fill: none; stroke: var(--edge); stroke-width: 1.3; }
+      #tg-estate .tg-edge-cross { stroke-dasharray: 5 4; stroke: var(--pending); }
+      #tg-estate .tg-estate-projects { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 10px; }
+      #tg-estate .tg-estate-project { border: 1px solid var(--rule); border-radius: var(--r-ctl); padding: 6px 8px; display: flex; flex-direction: column; gap: 4px; }
+      #tg-estate .tg-estate-title { font-weight: 600; overflow-wrap: anywhere; }
+      #tg-estate .ws-gate { border: 1px solid var(--pending, var(--rule)); border-radius: var(--r-ctl); padding: 4px 6px; }
+      #tg-estate .tg-estate-cmd { display: flex; gap: 6px; align-items: center; }
+      #tg-estate .tg-command { font-family: var(--font-mono); overflow-wrap: anywhere; }
       #tab-terragucci .tg-plan { color: var(--fg); }
       #tab-terragucci .tg-none, #tab-terragucci .tg-ok { color: var(--muted); }
       #tab-terragucci a { color: inherit; }
+      /* #506: the audit record's lane, in the tab and in a card's inspect pane. */
+      #tab-terragucci .tg-timeline-title { font-weight: 600; border-top: 1px solid var(--rule); padding-top: 6px; }
+      .tg-timeline { display: flex; flex-direction: column; gap: 3px; font-size: var(--t-caption); }
+      .rel-strip { border-collapse: collapse; margin: 6px 0; font-size: 12px; }
+      .rel-strip th, .rel-strip td { padding: 3px 6px; text-align: left; vertical-align: top; border-bottom: 1px solid var(--neutral); }
+      .rel-strip .rel-component { font-family: var(--font-mono); overflow-wrap: anywhere; }
+      .rel-strip .rel-cell { font-family: var(--font-mono); }
+      .rel-strip .rel-empty { color: var(--muted); }
+      .rel-strip .rel-differs { box-shadow: inset 2px 0 0 var(--degraded); }
+      .rel-strip .rel-mark { color: var(--degraded); font-weight: 600; font-family: inherit; }
+      .tg-timeline .tg-legend { color: var(--muted); }
+      .tg-timeline .tg-refusal { color: var(--degraded); font-weight: 600; }
+      .tg-timeline .tg-entry { overflow-wrap: anywhere; }
+      .tg-timeline .tg-when { color: var(--muted); font-family: var(--font-mono); }
+      .tg-timeline .tg-failed, .tg-timeline .tg-drift { color: var(--degraded); }
+      .tg-timeline .tg-wave { color: var(--pending); }
+      .tg-timeline a { color: inherit; }
       /* Fit reset + a zoom hint, floating top-right of the graph pane. */
       #zoom-toggle { position: absolute; top: 8px; right: 8px; z-index: 2; background: var(--panel);
         color: var(--muted); border: 1px solid var(--rule); border-radius: var(--r-ctl); padding: 4px 10px;

package/web/releases.js

@@ -0,0 +1,121 @@
+// #525: the Releases strip. Pure words from /api/lifecycle/releases, and one
+// render. One column per environment (wave order when yodel-waves.json gives
+// one), one row per component or tenant. Every cell says when its release was
+// recorded, by whom, and which commit of chant/lifecycle it was read from. A
+// cell whose digest the environment before it does not hold is marked
+// "differs from <env>" with both digests. Nothing here deploys or promotes.
+
+import { ago, clock } from "./terragucci.js";
+
+const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
+
+/** The strip's line: what was read, how, and when. */
+export function releasesLegend(a, now = new Date()) {
+  if (!a || a.error) return { text: `release ledger not read${a && a.error ? `: ${a.error}` : ""}`, title: "", tone: "refusal" };
+  const when = `read ${ago(a.read.at, now)}`;
+  if (!a.found) {
+    const text = a.via === "none" ? `release ledger unknown: behold could not fetch chant/lifecycle · ${when}` : `no release recorded yet · ${when}`;
+    return { text, title: a.note, tone: a.via === "none" ? "refusal" : "quiet" };
+  }
+  const how = a.via === "fetch" ? "fetched from origin" : "the checkout's origin/chant/lifecycle, as of its last git fetch (behold's fetch failed)";
+  const order = a.order === "waves" ? "columns in yodel-waves.json's wave order" : "columns by name";
+  const bad = Object.entries(a.malformed || {}).map(([env, n]) => `${env}: ${n} malformed line${n === 1 ? "" : "s"} skipped`);
+  return {
+    text: `release ledger on chant/lifecycle · ${when}, ${how} · ${order}`,
+    title: [a.note, a.fetch && a.fetch.error ? `fetch: ${a.fetch.error}` : "", ...bad].filter(Boolean).join("\n"),
+    tone: a.via === "fetch" ? "quiet" : "stale",
+  };
+}
+
+/** One cell's words: digest, age, who, and a difference mark when there is one. */
+export function releaseCellWords(cell, now = new Date()) {
+  if (!cell) return { text: "no release", title: "", differs: null };
+  const who = `${cell.actor}${cell.approver ? `, approved by ${cell.approver}` : ""}`;
+  const src = cell.source && cell.source.commit ? `chant/lifecycle ${short(cell.source.commit)}${cell.source.committed ? `, committed ${clock(cell.source.committed, now)}` : ""}` : "chant/lifecycle";
+  let differs = null;
+  if (cell.differs) {
+    const theirs = cell.differs.digest ? short(cell.differs.digest) : "nothing";
+    differs = {
+      text: `differs from ${cell.differs.from}`,
+      title: `${cell.env} holds ${short(cell.digest)}; ${cell.differs.from} holds ${theirs}.${cell.differs.everHad ? "" : ` ${cell.differs.from}'s ledger never recorded ${short(cell.digest)}.`}`,
+    };
+  }
+  return {
+    text: `${short(cell.digest)} · ${ago(cell.timestamp, now)}`,
+    title: [
+      `${cell.component} in ${cell.env}`,
+      `digest ${cell.digest}`,
+      `recorded ${clock(cell.timestamp, now)}, ${ago(cell.timestamp, now)}, by ${who}`,
+      `commit ${short(cell.gitSha)}, run ${cell.runId}`,
+      `from ${src} (${cell.source ? cell.source.path : ""})`,
+      differs ? differs.title : "",
+    ]
+      .filter(Boolean)
+      .join("\n"),
+    differs,
+  };
+}
+
+/** The grid: header row of environments, then a row per component with a cell per environment. */
+export function releaseGrid(a, now = new Date()) {
+  if (!a || !a.found) return { environments: [], rows: [] };
+  const at = new Map(a.cells.map((c) => [`${c.component}\u0000${c.env}`, c]));
+  return {
+    environments: a.environments,
+    rows: a.components.map((component) => ({
+      component,
+      cells: a.environments.map((env) => {
+        const c = at.get(`${component}\u0000${env}`);
+        return { env, ...releaseCellWords(c, now), runUrl: c && c.runUrl ? c.runUrl : null, empty: !c };
+      }),
+    })),
+  };
+}
+
+/** Render into `host`. `ui.link(text, href)` is app.js's link. */
+export function renderReleases(host, a, now, ui) {
+  host.replaceChildren();
+  const lg = releasesLegend(a, now);
+  const head = document.createElement("div");
+  head.className = lg.tone === "refusal" ? "tg-refusal" : "tg-legend";
+  head.textContent = lg.text;
+  head.title = lg.title;
+  host.appendChild(head);
+  const g = releaseGrid(a, now);
+  if (!g.rows.length) return;
+  const table = document.createElement("table");
+  table.className = "rel-strip";
+  const tr = document.createElement("tr");
+  tr.appendChild(document.createElement("th"));
+  for (const env of g.environments) {
+    const th = document.createElement("th");
+    th.textContent = env;
+    tr.appendChild(th);
+  }
+  table.appendChild(tr);
+  for (const row of g.rows) {
+    const r = document.createElement("tr");
+    const name = document.createElement("th");
+    name.className = "rel-component";
+    name.textContent = row.component;
+    r.appendChild(name);
+    for (const c of row.cells) {
+      const td = document.createElement("td");
+      td.className = c.empty ? "rel-cell rel-empty" : c.differs ? "rel-cell rel-differs" : "rel-cell";
+      td.title = c.title;
+      const t = document.createElement("div");
+      t.textContent = c.text;
+      td.appendChild(t);
+      if (c.differs) {
+        const d = document.createElement("div");
+        d.className = "rel-mark";
+        d.textContent = c.differs.text;
+        td.appendChild(d);
+      }
+      if (c.runUrl && ui && ui.link) td.appendChild(ui.link("run", c.runUrl));
+      r.appendChild(td);
+    }
+    table.appendChild(r);
+  }
+  host.appendChild(table);
+}

package/web/sql-yodeler-lane.js

@@ -0,0 +1,129 @@
+// #524: a SQL Yodeler repo's lane, from /api/sql-yodeler/lifecycle. One row
+// per environment in the order of applies (yodel-waves.json), each with its
+// wave's gate and its migrations op's gate: the state, the plan digest, who
+// approved and how, and the chant/lifecycle commit it was read from. A
+// waiting gate offers `npx yodel approve <env> --plan <digest>` to copy;
+// nothing here approves.
+
+import { ago, clock } from "./terragucci.js";
+import { holderWords, laneLegend, modeWords, sourceWords } from "./terragucci-lifecycle.js";
+
+const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
+
+const STATE_WORDS = {
+  waiting: "waits for an approval",
+  expired: "asked for an approval that expired",
+  approved: "approved, not applied yet",
+  applied: "applied",
+  failed: "apply failed",
+  refused: "refused: an approval stands for another plan",
+  "refused-by-policy": "refused by policy, no override counts",
+  held: "held on another gate",
+};
+
+/** The line over the lane: what was read, how, when, and where the order came from. */
+export function yodelLegend(answer, now = new Date()) {
+  const lg = laneLegend(answer, now);
+  if (!answer || answer.error) return lg;
+  const order = answer.order && answer.order.source === "yodel-waves.json" ? "environments in yodel-waves.json's order" : answer.order && answer.order.source === "ops" ? "environments from ops/migrate-<env>.op.ts (no yodel-waves.json)" : "no environments declared";
+  const member = answer.member && answer.member.members.length ? ` · workspace member ${answer.member.members.join(" / ")}, read under ${answer.member.prefix}` : "";
+  return { ...lg, text: `${lg.text} · ${order}${member}`, title: [lg.title, answer.order && answer.order.error ? `yodel-waves.json: ${answer.order.error}` : "", answer.member && answer.member.error ? answer.member.error : ""].filter(Boolean).join("\n") };
+}
+
+/** One gate as a card: title, facts, source, and the line to copy when it waits. Pure. */
+export function yodelGateCard(env, g, now = new Date()) {
+  const what = g.kind === "wave" ? `wave ${g.wave} (${g.gate})` : `${g.op} (${g.gate})`;
+  const facts = [];
+  if (g.pending) facts.push(`asked ${clock(g.pending.timestamp, now)}, ${ago(g.pending.timestamp, now)}`);
+  if (g.approval) {
+    const how = [g.approval.signed ? "signed" : "unsigned", g.approval.via ? `via ${g.approval.via}` : "", g.approval.pr !== undefined ? `PR #${g.approval.pr}` : "", g.approval.relayedBy ? `relayed by ${g.approval.relayedBy}` : ""].filter(Boolean).join(", ");
+    facts.push(`approved by ${g.approval.by} (${how}) ${clock(g.approval.at, now)}, ${ago(g.approval.at, now)}`);
+  }
+  if (g.applied) facts.push(`applied ${clock(g.applied.at, now)}, ${ago(g.applied.at, now)}${g.applied.result ? "" : " (outcome not recorded)"}`);
+  if (g.digest) facts.push(`plan ${short(g.digest)}`);
+  for (const u of g.uncounted || []) facts.push(`${u.approval.by}'s approval does not count: ${u.reason}`);
+  if (g.heldOn) facts.push(`held on ${g.heldOn.op}/${g.heldOn.gate}${holderWords(g.heldOn) ? `, ${holderWords(g.heldOn)}` : ""}`);
+  if (modeWords(g)) facts.push(modeWords(g));
+  if ((g.headPlans || []).length) {
+    const h = g.headPlans[0];
+    facts.push(`pull request head ${h.head.slice(0, 12)} recorded this plan ${clock(h.timestamp, now)}, ${ago(h.timestamp, now)} (${h.path}): a writer's approving review of that head, merged, approves it${g.headPlans.length > 1 ? `; ${g.headPlans.length - 1} more head${g.headPlans.length > 2 ? "s" : ""} recorded it too` : ""}`);
+  }
+  return {
+    env,
+    kind: g.kind,
+    state: g.state,
+    tone: g.state === "waiting" || g.state === "held" ? "wave" : g.state === "failed" || g.state === "refused" || g.state === "refused-by-policy" ? "failed" : g.state === "expired" ? "none" : "ok",
+    title: `${env}: ${what} ${STATE_WORDS[g.state] || g.state}`,
+    facts: facts.join(" · "),
+    source: sourceWords(g.source, now),
+    ...(g.command ? { command: g.command } : {}),
+    ...(g.pending && g.pending.url ? { job: g.pending.url } : {}),
+  };
+}
+
+/** Every environment's rows, in the order of applies. An environment with no gate on the ledger says so. Pure. */
+export function yodelRows(answer, now = new Date()) {
+  if (!answer || answer.error || !answer.found) return [];
+  const rows = [];
+  for (const e of answer.environments || []) {
+    const head = e.wave ? `${e.env}: wave ${e.wave.k}${e.wave.gate ? `, gate ${e.wave.gate}` : ""}${e.wave.approval ? `, approval ${e.wave.approval}` : ""}${e.wave.targets.length > 1 || e.wave.targets[0] !== e.env ? `, ${e.wave.targets.join(", ")}` : ""}` : `${e.env}: in no wave`;
+    rows.push({ env: e.env, head, cards: e.gates.map((g) => yodelGateCard(e.env, g, now)) });
+  }
+  if ((answer.unplaced || []).length) rows.push({ env: "", head: "waves yodel-waves.json does not name", cards: answer.unplaced.map((g) => yodelGateCard(`wave ${g.wave}`, g, now)) });
+  return rows;
+}
+
+const APPROVE_NOTE = "An approval is a git record bound to this plan digest: run the line at your shell. behold does not approve.";
+
+/** The lane as DOM. `ui` lends app.js's `button`, `copy` and `link`; a Copy button is the only control. */
+export function renderYodelLane(host, answer, now, ui) {
+  const lg = yodelLegend(answer, now);
+  const head = document.createElement("div");
+  head.className = lg.tone === "refusal" ? "tg-refusal" : "tg-legend";
+  head.textContent = lg.text;
+  head.title = lg.title || "";
+  host.appendChild(head);
+  for (const r of yodelRows(answer, now)) {
+    const h = document.createElement("h3");
+    h.textContent = r.head;
+    host.appendChild(h);
+    if (!r.cards.length) {
+      const none = document.createElement("div");
+      none.className = "tg-legend";
+      none.textContent = "no gate on chant/lifecycle yet";
+      host.appendChild(none);
+    }
+    for (const c of r.cards) {
+      const box = document.createElement("div");
+      box.className = `ws-gate tg-lane-gate tg-${c.tone}`;
+      const title = document.createElement("div");
+      title.className = "ws-gate-title";
+      title.textContent = c.title;
+      const facts = document.createElement("div");
+      facts.className = "ws-gate-facts";
+      facts.textContent = c.facts;
+      const src = document.createElement("div");
+      src.className = "ws-gate-note";
+      src.textContent = `from ${c.source}`;
+      box.append(title, facts, src);
+      if (c.command) {
+        const cmd = document.createElement("code");
+        cmd.className = "tg-command";
+        cmd.textContent = c.command;
+        const copy = ui.button("Copy", "", () => ui.copy(c.command, copy));
+        copy.title = "Copy the line. Run it at your shell: the approval is yours.";
+        const note = document.createElement("div");
+        note.className = "ws-gate-note";
+        note.textContent = APPROVE_NOTE;
+        box.append(cmd, copy, note);
+      }
+      if (c.job) {
+        const links = document.createElement("div");
+        links.className = "ws-gate-note";
+        links.appendChild(ui.link("job", c.job));
+        box.appendChild(links);
+      }
+      host.appendChild(box);
+    }
+  }
+}

package/web/terragucci-estate.js

@@ -0,0 +1,328 @@
+// #509: a terragucci control repo, across its projects. app.js calls
+// initTerragucciEstate once; when /api/project names a control repo, this reads
+// /api/terragucci/estate and draws it over the (empty) graph area:
+//
+// - one box per project, its roots grouped by wave inside it, a solid arrow
+//   for each read within a project and a dashed one for each read between
+//   projects (an arrow points from a root to the root that reads its state,
+//   as on terragucci's estate page);
+// - on each box, terragucci's counts and the run view it was drawn from,
+//   each with its age and source;
+// - below, per project, its waiting waves with the approve line to copy (no
+//   button approves), its links, and how to serve its own checkout.
+//
+// A project with no run view is drawn as a box that says so, never dropped.
+// Nothing here is live: every figure is dated by estate.json's `generated` or
+// a run view's `updated`. The layout functions are pure and tested.
+
+import { ago, clock } from "./terragucci.js";
+
+export const COL_W = 176;
+export const ROW_H = 26;
+export const PAD = 12;
+export const HEAD_H = 64;
+export const WAVE_H = 22;
+export const GAP = 72;
+export const NO_RUN_W = 300;
+
+/** The address a key opens at: this server's file route. */
+export function keyHref(answer, key) {
+  return `${answer.files || ""}${answer.files && answer.files.includes("?") ? encodeURIComponent(key) : key}`;
+}
+
+/**
+ * Projects in drawing order: a project whose roots another reads comes before
+ * the reader, so a dashed edge runs left to right where it can. Ties keep
+ * estate.json's order.
+ */
+export function projectOrder(answer) {
+  const names = answer.projects.map((p) => p.project);
+  const before = new Map(names.map((n) => [n, new Set()]));
+  for (const e of answer.edges || []) if (e.cross && before.has(e.to.project) && before.has(e.from.project)) before.get(e.to.project).add(e.from.project);
+  const out = [];
+  const seen = new Set();
+  const visit = (n, stack) => {
+    if (seen.has(n) || stack.has(n)) return;
+    stack.add(n);
+    for (const m of names) if (before.get(n).has(m)) visit(m, stack);
+    stack.delete(n);
+    seen.add(n);
+    out.push(n);
+  };
+  for (const n of names) visit(n, new Set());
+  return out.map((n) => answer.projects.find((p) => p.project === n));
+}
+
+/** The waves a project's box has columns for: its run view's waves and any wave a root names, ascending. */
+export function wavesOf(run) {
+  const n = new Set([...(run.waves || []).map((w) => w.number), ...(run.roots || []).map((r) => r.wave)]);
+  return [...n].sort((a, b) => a - b);
+}
+
+/**
+ * Where everything goes: each project's box, each wave column in it, each
+ * root's rect, and each edge's path. Coordinates are SVG user units.
+ */
+export function estateLayout(answer) {
+  const boxes = [];
+  const at = new Map(); // "project\u0000root" -> rect
+  let x = PAD;
+  let height = 0;
+  for (const p of projectOrder(answer)) {
+    const run = p.run;
+    const waves = run ? wavesOf(run) : [];
+    const rows = run ? Math.max(1, ...waves.map((n) => run.roots.filter((r) => r.wave === n).length)) : 0;
+    const w = run && waves.length ? waves.length * COL_W + PAD * 2 : NO_RUN_W;
+    const h = run ? HEAD_H + WAVE_H + rows * ROW_H + PAD : HEAD_H + PAD;
+    const box = { project: p.project, x, y: PAD, w, h, waves: [] };
+    if (run) {
+      waves.forEach((n, i) => {
+        const wx = x + PAD + i * COL_W;
+        const meta = run.waves.find((v) => v.number === n);
+        const roots = run.roots
+          .filter((r) => r.wave === n)
+          .sort((a, b) => (a.root < b.root ? -1 : 1))
+          .map((r, j) => {
+            const rect = { root: r.root, x: wx, y: PAD + HEAD_H + WAVE_H + j * ROW_H, w: COL_W - 16, h: ROW_H - 6 };
+            at.set(`${p.project}\u0000${r.root}`, rect);
+            return rect;
+          });
+        box.waves.push({ number: n, x: wx, y: PAD + HEAD_H, state: meta ? meta.state : "not-started", roots });
+      });
+    }
+    boxes.push(box);
+    x += w + GAP;
+    height = Math.max(height, box.y + h);
+  }
+  const edges = [];
+  for (const e of answer.edges || []) {
+    const a = at.get(`${e.from.project}\u0000${e.from.root}`);
+    const b = at.get(`${e.to.project}\u0000${e.to.root}`);
+    if (!a || !b) continue;
+    const x1 = a.x + a.w;
+    const y1 = a.y + a.h / 2;
+    const x2 = b.x;
+    const y2 = b.y + b.h / 2;
+    const bend = Math.max(36, Math.abs(x2 - x1) / 3);
+    edges.push({ from: e.from, to: e.to, cross: !!e.cross, d: `M${x1},${y1} C${x1 + bend},${y1} ${x2 - bend},${y2} ${x2},${y2}` });
+  }
+  return { width: Math.max(x - GAP + PAD, NO_RUN_W + PAD * 2), height: height + PAD, boxes, edges };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** terragucci's counts for a project, with their age and source. */
+export function countsLine(p, now = new Date()) {
+  if (!p.counts) return { text: p.status === "not-in-estate" ? "not in estate.json" : "no counts", title: p.missing || "" };
+  const c = p.counts;
+  return {
+    text: `${plural(c.drifted, "root")} drifted · ${c.failed} failed · ${plural(c.waiting, "wave")} waiting · ${ago(c.dated.at, now)}`,
+    title: `from ${c.dated.key}, generated ${clock(c.dated.at, now)} (${ago(c.dated.at, now)}); not live`,
+  };
+}
+
+/** Which run view the box was drawn from, or why it has none. */
+export function runLine(p, now = new Date()) {
+  if (p.run) {
+    return {
+      text: `run view ${p.run.commit.slice(0, 12)} · updated ${ago(p.run.updated, now)}`,
+      title: `${p.run.key}, the run view of ${p.run.commit}, named by estate.json's ${p.run.from === "run_view" ? "run_view" : "newest apply"}; a wave last wrote it ${clock(p.run.updated, now)}`,
+      tone: "ok",
+    };
+  }
+  if (p.refused) return { text: "run view refused", title: `${p.refused.error}\n${p.refused.remedy}`, tone: "bad" };
+  return { text: "no run view", title: p.missing || "no run view", tone: "none" };
+}
+
+/** A waiting wave as a line and its approve command. */
+export function waitingRows(p, now = new Date()) {
+  return (p.waiting || []).map((w) => ({
+    text: `wave ${w.wave} waiting since ${clock(w.since, now)}, ${ago(w.since, now)} · commit ${w.commit.slice(0, 12)}${w.digest ? ` · plan ${String(w.digest).replace(/^jcs1-sha256:/, "").slice(0, 12)}` : ""}`,
+    title: `from ${w.dated.key}, generated ${clock(w.dated.at, now)}`,
+    command: w.command,
+    digestKnown: !!w.digest,
+    report: w.report,
+  }));
+}
+
+/** The line over the picture: whose estate, how old, how checked. */
+export function estateLegend(answer, now = new Date()) {
+  const cross = (answer.edges || []).filter((e) => e.cross).length;
+  const drawn = answer.projects.filter((p) => p.run).length;
+  const checked = (v) => (v.by === "schema" ? `terragucci ${v.terragucci}'s schema` : "a structural check");
+  return {
+    text: `terragucci estate of ${plural(answer.projects.length, "project")}, not live · estate.json generated ${ago(answer.estate.generated, now)} · ${drawn} drawn from a run view · ${plural(cross, "read")} between projects`,
+    title: [`read from ${answer.source} (${answer.gets} GETs)`, `estate.json checked with ${checked(answer.validation.estate)}`, `run views checked with ${checked(answer.validation.run)}`, `config: ${answer.config}`].join("\n"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The DOM. Text only, never innerHTML: every string here came from a bucket.
+// ---------------------------------------------------------------------------
+
+const SVG = "http://www.w3.org/2000/svg";
+
+function el(doc, tag, cls, text) {
+  const e = doc.createElement(tag);
+  if (cls) e.className = cls;
+  if (text !== undefined) e.textContent = text;
+  return e;
+}
+function svgEl(doc, tag, attrs = {}, text) {
+  const e = doc.createElementNS(SVG, tag);
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, String(v));
+  if (text !== undefined) e.textContent = text;
+  return e;
+}
+function link(doc, text, href) {
+  const a = el(doc, "a", "", text);
+  a.href = href;
+  a.target = "_blank";
+  a.rel = "noopener";
+  return a;
+}
+function titled(doc, node, title) {
+  if (title) node.appendChild(svgEl(doc, "title", {}, title));
+  return node;
+}
+
+/** The picture: boxes, wave columns, roots and edges. */
+export function renderEstateSvg(answer, now = new Date(), doc = document) {
+  const L = estateLayout(answer);
+  const svg = svgEl(doc, "svg", { width: L.width, height: L.height, viewBox: `0 0 ${L.width} ${L.height}`, class: "tg-estate-svg", role: "img", "aria-label": "terragucci estate: projects, their roots by wave, and the reads between them" });
+  const defs = svgEl(doc, "defs");
+  const marker = svgEl(doc, "marker", { id: "tg-estate-arrow", viewBox: "0 0 10 10", refX: 9, refY: 5, markerWidth: 7, markerHeight: 7, orient: "auto-start-reverse" });
+  marker.appendChild(svgEl(doc, "path", { d: "M0,0 L10,5 L0,10 z", fill: "var(--edge)" }));
+  defs.appendChild(marker);
+  svg.appendChild(defs);
+  const byName = new Map(answer.projects.map((p) => [p.project, p]));
+  for (const b of L.boxes) {
+    const p = byName.get(b.project);
+    const g = svgEl(doc, "g", { class: "tg-project", "data-project": b.project });
+    g.appendChild(svgEl(doc, "rect", { x: b.x, y: b.y, width: b.w, height: b.h, rx: 6, class: `tg-project-box${p.run ? "" : " tg-no-run"}` }));
+    const name = svgEl(doc, "text", { x: b.x + PAD, y: b.y + 20, class: "tg-project-name" }, b.project);
+    if (p.index) {
+      const a = svgEl(doc, "a", { href: keyHref(answer, p.index), target: "_blank" });
+      a.appendChild(name);
+      g.appendChild(a);
+    } else g.appendChild(name);
+    const counts = countsLine(p, now);
+    g.appendChild(titled(doc, svgEl(doc, "text", { x: b.x + PAD, y: b.y + 38, class: "tg-project-counts" }, counts.text), counts.title));
+    const run = runLine(p, now);
+    g.appendChild(titled(doc, svgEl(doc, "text", { x: b.x + PAD, y: b.y + 55, class: `tg-project-run tg-${run.tone}` }, run.text), run.title));
+    for (const w of b.waves) {
+      g.appendChild(svgEl(doc, "text", { x: w.x, y: w.y + 14, class: `tg-wave-label tg-wave-${w.state}`, "data-wave": w.number }, `wave ${w.number} · ${w.state === "not-started" ? "not started" : w.state}`));
+      for (const r of w.roots) {
+        const node = svgEl(doc, "g", { class: "tg-root-node", "data-root": r.root });
+        node.appendChild(svgEl(doc, "rect", { x: r.x, y: r.y, width: r.w, height: r.h, rx: 4 }));
+        node.appendChild(titled(doc, svgEl(doc, "text", { x: r.x + 6, y: r.y + r.h / 2 + 4 }, r.root.length > 24 ? `…${r.root.slice(-23)}` : r.root), `${b.project}: ${r.root}, wave ${w.number}`));
+        g.appendChild(node);
+      }
+    }
+    svg.appendChild(g);
+  }
+  for (const e of L.edges) {
+    const path = svgEl(doc, "path", { d: e.d, class: `tg-edge${e.cross ? " tg-edge-cross" : ""}`, "marker-end": "url(#tg-estate-arrow)", "data-from": `${e.from.project} ${e.from.root}`, "data-to": `${e.to.project} ${e.to.root}` });
+    svg.appendChild(titled(doc, path, `${e.to.project}: ${e.to.root} reads ${e.from.project}: ${e.from.root}`));
+  }
+  return svg;
+}
+
+/** Draw the whole view into `host`. `copy(text, buttonEl)` puts a line on the clipboard. */
+export function renderEstate(host, answer, { copy = () => {}, refresh, now = new Date(), doc = document } = {}) {
+  host.replaceChildren();
+  if (!answer || answer.error) {
+    host.append(el(doc, "div", "tg-refusal", answer ? answer.error : "the estate was not read"), el(doc, "div", "tg-legend", (answer && answer.remedy) || ""));
+    return;
+  }
+  const lg = estateLegend(answer, now);
+  const head = el(doc, "div", "tg-legend", lg.text);
+  head.title = lg.title;
+  const top = el(doc, "div", "tg-estate-head");
+  top.append(head, link(doc, "terragucci's estate page", keyHref(answer, answer.estate.html)));
+  if (refresh) {
+    const again = el(doc, "button", "", "Read again");
+    again.addEventListener("click", refresh);
+    top.appendChild(again);
+  }
+  host.appendChild(top);
+  const wrap = el(doc, "div", "tg-estate-graph");
+  wrap.appendChild(renderEstateSvg(answer, now, doc));
+  host.appendChild(wrap);
+  const list = el(doc, "div", "tg-estate-projects");
+  const copyRow = (text) => {
+    const row = el(doc, "div", "tg-estate-cmd");
+    const code = el(doc, "code", "tg-command", text);
+    const b = el(doc, "button", "", "Copy");
+    b.title = "Copy the line and run it at your shell. behold runs nothing here.";
+    b.addEventListener("click", () => copy(text, b));
+    row.append(code, b);
+    return row;
+  };
+  for (const p of projectOrder(answer)) {
+    const card = el(doc, "section", "tg-estate-project");
+    card.dataset.project = p.project;
+    const title = el(doc, "div", "tg-estate-title", p.project);
+    card.appendChild(title);
+    const links = el(doc, "div", "tg-legend");
+    const parts = [];
+    if (p.index) parts.push(link(doc, "its index", keyHref(answer, p.index)));
+    parts.push(link(doc, "estate.html", keyHref(answer, answer.estate.html)));
+    if (p.run) parts.push(link(doc, "run view", keyHref(answer, p.run.page)));
+    parts.forEach((a, i) => links.append(...(i ? [" · ", a] : [a])));
+    card.appendChild(links);
+    const counts = countsLine(p, now);
+    const c = el(doc, "div", "tg-estate-counts", counts.text);
+    c.title = counts.title;
+    card.appendChild(c);
+    const run = runLine(p, now);
+    const r = el(doc, "div", `tg-estate-run tg-${run.tone}`, run.tone === "ok" ? run.text : `${run.text}: ${p.refused ? p.refused.error : p.missing || ""}`);
+    r.title = run.title;
+    card.appendChild(r);
+    for (const w of waitingRows(p, now)) {
+      const box = el(doc, "div", "ws-gate tg-wave");
+      const t = el(doc, "div", "ws-gate-facts", w.text);
+      t.title = w.title;
+      box.append(t, copyRow(w.command));
+      const note = el(doc, "div", "ws-gate-note", w.digestKnown ? "Run it in the project's own checkout: the approval is a signed git record bound to this plan digest. behold does not approve." : "Run it in the project's own checkout, with the plan digest from the wave's report. behold does not approve.");
+      box.appendChild(note);
+      if (w.report) {
+        const l = el(doc, "div", "ws-gate-note");
+        l.appendChild(link(doc, "report", keyHref(answer, w.report)));
+        box.appendChild(l);
+      }
+      card.appendChild(box);
+    }
+    if (p.checkout) {
+      card.appendChild(el(doc, "div", "tg-legend", `checked out at ${p.checkout.path}; serve it to see its roots:`));
+      card.appendChild(copyRow(p.checkout.command));
+    }
+    list.appendChild(card);
+  }
+  host.appendChild(list);
+}
+
+/**
+ * Once, at boot: when /api/project names a terragucci control repo, read the
+ * estate and draw it in a layer over the graph area. `fetchUrl(url)` is
+ * app.js's apiFetch, `copy` its copyToClipboard.
+ */
+export async function initTerragucciEstate({ fetchUrl, copy, doc = document } = {}) {
+  const project = await fetchUrl("/api/project").then((r) => r.json()).catch(() => ({}));
+  if (!project.terragucciControl || !project.terragucciReports) return;
+  const graph = doc.getElementById("graph");
+  if (!graph || !graph.parentElement) return;
+  let host = doc.getElementById("tg-estate");
+  if (!host) {
+    host = el(doc, "div");
+    host.id = "tg-estate";
+    graph.parentElement.insertBefore(host, graph.nextSibling);
+  }
+  const load = async (fresh) => {
+    const answer = await fetchUrl(`/api/terragucci/estate${fresh ? "?fresh=1" : ""}`)
+      .then((r) => r.json())
+      .catch((e) => ({ error: String(e), code: "terragucci-report", remedy: "" }));
+    renderEstate(host, answer, { copy, refresh: () => load(true), doc });
+  };
+  await load(false);
+}