@intentius/behold 0.25.0 → 0.26.0

package/web/terragucci-lifecycle.js

@@ -28,8 +28,12 @@ export function laneLegend(lane, now = new Date(), polled = null) {
   }
   const how = lane.via === "fetch" ? "fetched from origin" : "the checkout's origin/chant/lifecycle, as of its last git fetch (behold's fetch failed)";
   return {
-    text: `chant/lifecycle at ${short(lane.commit.sha)}, committed ${ago(lane.commit.committed, now)} · ${when}, ${how}`,
-    title: [lane.note, lane.fetch && lane.fetch.error ? `fetch: ${lane.fetch.error}` : ""].filter(Boolean).join("\n"),
+    text: `chant/lifecycle at ${short(lane.commit.sha)}, committed ${ago(lane.commit.committed, now)} · ${when}, ${how}${lane.approval && lane.approval.inferred ? ` · approval mode ${lane.approval.mode} at base, for the waves whose requests record none` : ""}`,
+    title: [
+      lane.note,
+      lane.approval ? `approvals counted: ${lane.approval.mode} (${lane.approval.source}${lane.approval.base ? `, base ${short(lane.approval.base)}` : ""})${lane.approval.inferred ? `; ${lane.approval.inferred}` : ""}${lane.approval.note ? `; ${lane.approval.note}` : ""}` : "",
+      lane.fetch && lane.fetch.error ? `fetch: ${lane.fetch.error}` : "",
+    ].filter(Boolean).join("\n"),
     tone: lane.via === "fetch" ? "quiet" : "stale",
   };
 }
@@ -38,28 +42,86 @@ const TITLE = {
   waiting: (g) => `wave ${g.wave} waits for an approval`,
   expired: (g) => `wave ${g.wave}'s request for an approval expired`,
   approved: (g) => `wave ${g.wave} approved by ${g.approval.by}, not applied yet`,
-  applied: (g) => `wave ${g.wave} applied`,
+  applied: (g) => (g.applied && !g.applied.result ? `wave ${g.wave} applied (outcome not recorded)` : `wave ${g.wave} applied`),
   failed: (g) => `wave ${g.wave}'s apply failed`,
+  refused: (g) => `wave ${g.wave} refused: an approval stands for other plans`,
+  "refused-by-policy": (g) => `wave ${g.wave} refused by policy: ${(g.denials || []).length} run${(g.denials || []).length === 1 ? "" : "s"} denied, no override counts`,
+  held: (g) => `wave ${g.wave} held on ${g.heldOn.op}/${g.heldOn.gate}${g.heldOn.heldBy ? ` by hook ${g.heldOn.heldBy.hook}` : ""}`,
 };
 
+/**
+ * Who holds a wave on another gate: the hook the fact names (`heldBy`,
+ * chant#3886), with the moment it ran at and its run; for a fact written
+ * before chant named it, the fact's description, which the hook wrote.
+ */
+export function holderWords(heldOn) {
+  if (!heldOn) return "";
+  const h = heldOn.heldBy;
+  if (h) return `held by hook ${h.hook} at ${h.moment}${h.target ? ` for ${h.target}` : ""}`;
+  return heldOn.description || "";
+}
+
+const NOTE = {
+  approve: "An approval is a signed git record bound to this plan digest: run the line at your shell. behold does not approve.",
+  answer: "This gate asks a decision point: answer it at your shell. behold does not answer.",
+  override: "An override is a person's git record with a reason, bound to this plan and these rules: run the line at your shell. behold does not override.",
+};
+
+/** The mode a wave is decided under: the one its request recorded (chant#3861), else the one read at base. */
+export function modeWords(g) {
+  if (!g.approvalMode) return "";
+  return g.approvalMode.from === "pending" ? `asked under ${g.approvalMode.mode}` : `approval mode ${g.approvalMode.mode}, read at base: its request records none`;
+}
+
+/** Who approved, and how: signed, relayed, from a pull request's review. */
+function approvalWords(a, now) {
+  const how = [
+    a.signed ? "signed" : "",
+    a.via ? `via ${a.via}` : "",
+    a.pr !== undefined ? `PR #${a.pr}${a.head ? ` at ${short(a.head)}` : ""}` : "",
+    a.reviewers && a.reviewers.length ? `reviewed by ${a.reviewers.join(", ")}` : "",
+    a.relayedBy ? `relayed by ${a.relayedBy}` : "",
+  ].filter(Boolean);
+  return `${a.by}${how.length ? ` (${how.join(", ")})` : ""} ${clock(a.at, now)}, ${ago(a.at, now)}`;
+}
+
 /** Each wave's gate as a card: its state, who and when, the digest, the commit it was read from, and for a waiting wave the line to run. No button. */
 export function laneGateCards(lane, now = new Date()) {
   if (!lane || !lane.found) return [];
   return lane.gates.map((g) => {
     const facts = [];
-    if (g.pending) facts.push(`asked ${clock(g.pending.timestamp, now)}, ${ago(g.pending.timestamp, now)}`);
-    if (g.approval) facts.push(`approved by ${g.approval.by}${g.approval.signed ? " (signed)" : ""}${g.approval.via ? ` via ${g.approval.via}` : ""} ${clock(g.approval.at, now)}, ${ago(g.approval.at, now)}`);
-    if (g.applied) facts.push(`${g.applied.result === "failed" ? "apply failed" : "applied"} ${clock(g.applied.finished || g.applied.at, now)}, ${ago(g.applied.finished || g.applied.at, now)}`);
+    const own = g.state !== "refused-by-policy" && g.state !== "held";
+    if (g.pending && own) facts.push(`asked ${clock(g.pending.timestamp, now)}, ${ago(g.pending.timestamp, now)}`);
+    if (g.pending && g.pending.description && own) facts.push(g.pending.description);
+    if (g.pending && g.pending.answer && g.state === "waiting") facts.push(`asks decision point ${g.pending.answer.point}`);
+    if (g.heldOn) facts.push(`held ${clock(g.heldOn.since, now)}, ${ago(g.heldOn.since, now)}; ${g.heldOn.op}/${g.heldOn.gate} waits${g.heldOn.digest ? ` for plan ${short(g.heldOn.digest)}` : ""}${g.heldOn.answer ? ` on decision point ${g.heldOn.answer.point}` : ""}`);
+    if (holderWords(g.heldOn)) facts.push(holderWords(g.heldOn));
+    if (g.approval) facts.push(`${g.state === "refused" ? `approved for plan ${short(g.refused && g.refused.digest) || "(none)"} by` : "approved by"} ${approvalWords(g.approval, now)}`);
+    if (g.applied) facts.push(`${g.applied.result === "failed" ? "apply failed" : "applied"} ${clock(g.applied.finished || g.applied.at, now)}, ${ago(g.applied.finished || g.applied.at, now)}${g.applied.review && g.applied.review.pr !== undefined ? ` under the review of PR #${g.applied.review.pr}` : ""}`);
     if (g.digest) facts.push(`plan ${short(g.digest)}`);
+    if (g.pending && g.pending.members && g.pending.members.length) facts.push(`${g.pending.members.length} root${g.pending.members.length === 1 ? "" : "s"}: ${g.pending.members.map((m) => m.member).join(", ")}`);
+    if (g.pending && g.pending.neverOverMcp) facts.push("never approved over MCP");
+    if (modeWords(g)) facts.push(modeWords(g));
+    if (g.identity) facts.push(`identity.gates at base: only a signed approval counts${g.identity.class ? `, from class ${g.identity.class}` : ""}`);
+    if (g.spent) facts.push(`the approval of plan ${short(g.spent.planDigest)} by ${g.spent.by} was spent by its apply`);
+    const uncounted = (g.uncounted || []).map((u) => `${u.approval.by}'s approval of this plan does not count: ${u.reason}`);
+    const overrides = (g.denials || []).map((d) => ({
+      text: `${d.member}: plan ${short(d.plan)} denied by ${d.rules.join(", ")} ${clock(d.at, now)}, ${ago(d.at, now)}${d.moved ? `; ${d.moved.by} overrode an earlier plan or other rules` : ""}${d.refusals.length ? `; ${d.refusals.join("; ")}` : ""}`,
+      command: d.command,
+      ...(d.url ? { job: d.url } : {}),
+    }));
+    const commandNote = (g.state === "held" ? g.heldOn && g.heldOn.answer : g.pending && g.pending.answer) ? NOTE.answer : NOTE.approve;
     return {
       wave: g.wave,
       state: g.state,
-      tone: g.state === "waiting" ? "wave" : g.state === "failed" ? "failed" : g.state === "expired" ? "none" : "ok",
+      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: TITLE[g.state] ? TITLE[g.state](g) : `wave ${g.wave}: ${g.state}`,
       facts: facts.join(" · "),
+      ...(uncounted.length ? { uncounted } : {}),
+      ...(overrides.length ? { overrides, overrideNote: NOTE.override } : {}),
       source: sourceWords(g.source, now),
-      ...(g.command ? { command: g.command, note: "An approval is a signed git record bound to this plan digest: run the line at your shell. behold does not approve." } : {}),
-      ...(g.pending && g.pending.url ? { job: g.pending.url } : {}),
+      ...(g.command ? { command: g.command, note: commandNote } : {}),
+      ...(g.heldOn && g.heldOn.url ? { job: g.heldOn.url } : g.pending && g.pending.url ? { job: g.pending.url } : {}),
     };
   });
 }
@@ -108,13 +170,43 @@ export function renderLane(host, lane, polled, now, ui) {
     const src = document.createElement("div");
     src.className = "ws-gate-note";
     src.textContent = `from ${g.source}`;
-    box.append(title, facts, src);
+    box.append(title, facts);
+    for (const u of g.uncounted || []) {
+      const why = document.createElement("div");
+      why.className = "ws-gate-note";
+      why.textContent = u;
+      box.appendChild(why);
+    }
+    box.appendChild(src);
+    for (const o of g.overrides || []) {
+      const what = document.createElement("div");
+      what.className = "ws-gate-note";
+      what.textContent = o.text;
+      const cmd = document.createElement("code");
+      cmd.className = "tg-command";
+      cmd.textContent = o.command;
+      const copy = ui.button("Copy", "", () => ui.copy(o.command, copy));
+      copy.title = "Copy the line. Run it at your shell, with your reason: the override is yours.";
+      box.append(what, cmd, copy);
+      if (o.job) {
+        const links = document.createElement("div");
+        links.className = "ws-gate-note";
+        links.appendChild(ui.link("job", o.job));
+        box.appendChild(links);
+      }
+    }
+    if (g.overrideNote) {
+      const n = document.createElement("div");
+      n.className = "ws-gate-note";
+      n.textContent = g.overrideNote;
+      box.appendChild(n);
+    }
     if (g.command) {
       const cmd = document.createElement("code");
       cmd.className = "tg-command";
       cmd.textContent = g.command;
       const copy = ui.button("Copy", "", () => ui.copy(g.command, copy));
-      copy.title = "Copy the line. Run it at your shell: the approval is yours, signed, in git.";
+      copy.title = "Copy the line. Run it at your shell: the approval or answer is yours.";
       const note = document.createElement("div");
       note.className = "ws-gate-note";
       note.textContent = g.note;

package/web/terragucci-lifecycle.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { laneGateCards, laneLegend, laneLockRows, sourceWords } from "./terragucci-lifecycle.js";
+import { holderWords, laneGateCards, laneLegend, laneLockRows, sourceWords } from "./terragucci-lifecycle.js";
 
 const NOW = new Date("2026-10-09T12:00:00Z");
 const source = { branch: "chant/lifecycle", commit: "1a2b3c4d5e6f7a8b", committed: "2026-10-09T10:00:00Z", path: "_gates/tf-apply.jsonl" };
@@ -52,6 +52,41 @@ describe("the chant/lifecycle lane, dated (#505)", () => {
     expect(two.tone).toBe("wave");
   });
 
+  it("shows the mode a wave asked under, and says when it was read at base instead (chant#3861)", () => {
+    const [one, two] = lane().gates;
+    const g = lane({
+      approval: { mode: "ledger", source: "the default", inferred: "a wave whose pending fact records no approval mode ..." },
+      gates: [{ ...one, approvalMode: { mode: "sealed", from: "pending" } }, { ...two, approvalMode: { mode: "ledger", from: "base" } }],
+    });
+    const [a, b] = laneGateCards(g, NOW);
+    expect(a.facts).toContain("asked under sealed");
+    expect(b.facts).toContain("approval mode ledger, read at base: its request records none");
+    expect(laneLegend(g, NOW).text).toContain("approval mode ledger at base, for the waves whose requests record none");
+    expect(laneLegend(lane({ approval: { mode: "ledger", source: "the default" } }), NOW).text).not.toContain("approval mode");
+  });
+
+  it("names an identity.gates gate's class without a caveat, and a hold by its fact (chant#3862, chant#3839)", () => {
+    const [one] = lane().gates;
+    const held = { ...one, state: "held", approval: undefined, heldOn: { op: "tf-migrate", gate: "move-db", since: "2026-10-09T10:00:00Z", description: "migrate the orders table first" }, identity: { class: "human" } };
+    const [c] = laneGateCards(lane({ gates: [held] }), NOW);
+    expect(c.facts).toContain("only a signed approval counts, from class human");
+    expect(c.facts).not.toContain("chant#3862");
+    expect(c.facts).toContain("held 10:00 UTC, 2h ago; tf-migrate/move-db waits");
+    expect(c.facts).toContain("migrate the orders table first");
+    expect(c.title).toBe("wave 1 held on tf-migrate/move-db");
+  });
+
+  it("names the hook that holds a wave from the fact's heldBy, before its description (chant#3886)", () => {
+    const [one] = lane().gates;
+    const heldOn = { op: "tf-migrate", gate: "move-db", since: "2026-10-09T10:00:00Z", heldBy: { hook: "migrate", moment: "after-plan", target: "vpc" }, description: "migrate the orders table first" };
+    const [c] = laneGateCards(lane({ gates: [{ ...one, state: "held", approval: undefined, heldOn }] }), NOW);
+    expect(c.title).toBe("wave 1 held on tf-migrate/move-db by hook migrate");
+    expect(c.facts).toContain("held by hook migrate at after-plan for vpc");
+    expect(c.facts).not.toContain("migrate the orders table first");
+    expect(holderWords({ ...heldOn, heldBy: { hook: "migrate", moment: "after-plan" } })).toBe("held by hook migrate at after-plan");
+    expect(holderWords({ ...heldOn, heldBy: undefined })).toBe("migrate the orders table first");
+  });
+
   it("words a lock with its holder, its age and its source", () => {
     const [l] = laneLockRows(lane(), NOW);
     expect(l.text).toBe("locked by PR #12 (carol, by an apply) 07:00 UTC, 5h ago");

package/web/terragucci-timeline.js

@@ -116,3 +116,80 @@ export function laneElement(answer, opts = {}) {
   }
   return box;
 }
+
+// #522: the gate ledgers' history on chant/lifecycle, from
+// /api/lifecycle/history (chant's gate-audit over `git log -p`). Drawn beside
+// the audit record, or alone when the source has no audit.jsonl, and labelled
+// "ledger" so the two are never mistaken for each other.
+
+const HISTORY_WORDS = {
+  "approval-requested": "approval requested",
+  approved: "approved",
+  "override-requested": "override requested",
+  "override-recorded": "policy overridden",
+  applied: "applied",
+  "override-spent": "override spent",
+};
+
+/** One ledger entry as a line: "approved wave-2 by dana: unsigned · plan 4be1…". */
+export function historyLine(entry) {
+  const what = entry.kind === "revoked" ? `${entry.subject || "approval"} revoked` : HISTORY_WORDS[entry.kind] || entry.kind;
+  const op = entry.op && entry.op !== "tf-apply" ? ` (${entry.op})` : "";
+  const by = entry.actor ? ` by ${entry.actor}` : "";
+  const seal = entry.seal && (entry.kind === "approved" || entry.kind === "override-recorded") ? `: ${entry.seal}` : "";
+  const digest = entry.digest ? ` · plan ${entry.digest.replace(/^(jcs1-)?sha256:/, "").slice(0, 12)}` : "";
+  return `${what} ${entry.gate}${op}${by}${seal}${digest}`;
+}
+
+/** The history's rows, newest first: clock, line, tone, and the line's file, commit and committer in the title. */
+export function historyRows(answer, { now = new Date() } = {}) {
+  if (!answer || !answer.entries) return [];
+  return answer.entries.map((e) => {
+    const s = e.source || {};
+    const commit = s.commit ? `${s.change === "removed" ? "removed" : "added"} in ${s.commit.slice(0, 12)}${s.committer ? ` by ${s.committer}` : ""}${s.committed ? ` at ${s.committed}` : ""}` : "";
+    return {
+      id: e.id,
+      when: `${clock(e.at, now)}, ${ago(e.at, now)}`,
+      text: historyLine(e),
+      tone: e.kind === "revoked" ? "drift" : e.kind.endsWith("-requested") ? "wave" : "ok",
+      title: [e.at, `${s.path}${s.line ? `:${s.line}` : ""}`, commit, e.note || ""].filter(Boolean).join("\n"),
+    };
+  });
+}
+
+/** The line over the history: its source, how many entries, where it was read from and how old. */
+export function historyLegend(answer, { shown = 0 } = {}) {
+  if (!answer) return "ledger history not read";
+  if (answer.error) return answer.error;
+  if (!answer.found) return `ledger: ${answer.note}`;
+  if (!shown) return `ledger: no gate record on ${answer.branch}`;
+  const more = answer.total > shown ? ` of ${answer.total}` : "";
+  const via = answer.via === "checkout-ref" ? " (the checkout's copy: the fetch failed)" : "";
+  const tip = answer.commit ? `, tip committed ${answer.commit.committed}` : "";
+  return `ledger: ${shown}${more} entr${shown === 1 ? "y" : "ies"} from the gate ledgers on ${answer.branch}${via}${tip}, newest first`;
+}
+
+/** The history as DOM. Browser-only (the tests take the pure functions above). */
+export function historyElement(answer, opts = {}) {
+  const rows = historyRows(answer, opts);
+  const box = document.createElement("div");
+  box.className = "tg-timeline";
+  const head = document.createElement("div");
+  head.className = answer && answer.error ? "tg-refusal" : "tg-legend";
+  head.textContent = historyLegend(answer, { shown: rows.length });
+  if (answer && answer.note) head.title = answer.note;
+  box.appendChild(head);
+  for (const r of rows) {
+    const row = document.createElement("div");
+    row.className = `tg-entry tg-${r.tone}`;
+    row.title = r.title;
+    const when = document.createElement("span");
+    when.className = "tg-when";
+    when.textContent = r.when;
+    const text = document.createElement("span");
+    text.textContent = ` ${r.text}`;
+    row.append(when, text);
+    box.appendChild(row);
+  }
+  return box;
+}

package/web/workspace-gates.js

@@ -18,6 +18,7 @@ export function gateCards(answer, { embed = false, member = null } = {}) {
   const all = (answer && answer.gates) || [];
   const shown = member ? all.filter((g) => g.member === member) : all;
   const cards = shown.map((g) => {
+    if (g.override) return overrideCard(g);
     const facts = [`${g.approvals.length} of ${g.needed} approval${g.needed === 1 ? "" : "s"}`];
     if (g.env) facts.push(`env ${g.env}`);
     if (g.planDigest) facts.push(`plan ${shortDigest(g.planDigest)}`);
@@ -38,6 +39,34 @@ export function gateCards(answer, { embed = false, member = null } = {}) {
   return { cards, elsewhere, refusal: (answer && answer.refusal) || null };
 }
 
+/**
+ * #519: a policy denial. chant's override needs the denied rules and a
+ * person's reason, so the card shows them and the command to run, and never a
+ * button, framed or not. An override that counts reads as overridden until a
+ * run applies it, then as spent.
+ */
+export function overrideCard(g) {
+  const o = g.override;
+  const facts = [];
+  facts.push(o.rules.length ? `denied by ${o.rules.join(", ")}` : "denied by rules the ledger did not name");
+  if (o.plan) facts.push(`plan ${shortDigest(o.plan)}`);
+  if (o.digest) facts.push(`override digest ${shortDigest(o.digest)}`);
+  if (g.recordedAt) facts.push(`denied ${g.recordedAt}`);
+  if (o.source) facts.push(`from ${o.source}`);
+  const card = { key: g.key, member: g.member, facts: facts.join(" · "), command: o.command, override: o.state };
+  if (o.state === "spent") {
+    card.title = `${g.member}: the override of ${o.subject} is spent`;
+    card.note = `a run applied under it${o.spentAt ? ` at ${o.spentAt}` : ""}; a new denial needs a new override`;
+  } else if (o.state === "overridden") {
+    card.title = `${g.member}: ${o.subject} is overridden`;
+    card.note = "an override counts for this plan; the next run applies it once";
+  } else {
+    card.title = `${g.member}: the policy denied ${o.subject}`;
+    card.note = `a reason is required. Override it at your shell: ${o.command}`;
+  }
+  return card;
+}
+
 function shortDigest(d) {
   const s = String(d).replace(/^sha256:/, "");
   return s.length > 12 ? s.slice(0, 12) : s;

package/web/yodel-report.js

@@ -0,0 +1,99 @@
+// #526: SQL Yodeler's report and drift, read from files by /api/yodel-report.
+// Pure helpers; app.js places the marks and draws the panel. A mark is a
+// dated corner tag, never a fill: none of this is live.
+import { ago, clock } from "./terragucci.js";
+
+/** The ids of the cards an object names: the id itself, or a member's `<member>/<name>`. */
+export function cardsFor(object, ids) {
+  return ids.filter((id) => id === object || id.endsWith("/" + object));
+}
+
+/** Join the read's marks onto the drawn card ids: marks by card, and the objects no card is. */
+export function joinMarks(answer, ids) {
+  const cards = {};
+  const unmatched = [];
+  for (const m of (answer && answer.marks) || []) {
+    const hit = cardsFor(m.object, ids);
+    if (hit.length === 0) unmatched.push(m);
+    for (const id of hit) (cards[id] ||= []).push(m);
+  }
+  return { cards, unmatched };
+}
+
+/** When and from where, in words: "drift-prod.json, written 06:04 UTC, 4h ago". */
+export function datedWords(dated, now = new Date()) {
+  const how = dated.by === "generatedAt" ? "generated" : "written";
+  return `${dated.file}, ${how} ${clock(dated.at, now)}, ${ago(dated.at, now)}`;
+}
+
+/** One mark as a line: "prod: changed out of band (ttl) · drift-prod.json, written 06:04 UTC, 4h ago". */
+export function markLine(m, now = new Date()) {
+  const paths = m.changes.map((c) => c.path).filter(Boolean);
+  return `${m.environment}: ${m.words}${paths.length ? ` (${paths.join(", ")})` : ""} · ${datedWords(m.dated, now)}`;
+}
+
+/** The corner tag for a card's marks: "drift prod · 4h", the age of the newest. */
+export function cornerText(marks, now = new Date()) {
+  const envs = [...new Set(marks.map((m) => m.environment))].join(", ");
+  const newest = marks.map((m) => m.dated.at).sort().pop();
+  const s = Math.max(0, (now.getTime() - Date.parse(newest)) / 1000);
+  const age = s < 3600 ? `${Math.max(1, Math.round(s / 60))}m` : s < 172800 ? `${Math.round(s / 3600)}h` : `${Math.round(s / 86400)}d`;
+  return `drift ${envs} · ${age}`;
+}
+
+/** The panel's lines for one environment, from the report. */
+export function environmentLines(e, now = new Date()) {
+  const lines = [];
+  if (e.error) lines.push(`could not be read: ${e.error}`);
+  const newest = e.applied[e.applied.length - 1];
+  lines.push(
+    `${e.applied.length} applied` +
+      (newest ? `, newest ${newest.id}${newest.at ? ` at ${clock(newest.at, now)}` : ""}${newest.by ? ` by ${newest.by}` : ""}` : ""),
+  );
+  for (const m of e.other) lines.push(`${m.id}: ${m.state}${m.inDirectory ? "" : " (not in the directory)"}`);
+  for (const g of e.gaps) lines.push(`gap (${g.kind}): ${g.detail}`);
+  for (const n of e.notes) lines.push(`note: ${n}`);
+  return lines;
+}
+
+/** The panel's head: what was read, how it was checked, and when. */
+export function legend(answer, now = new Date()) {
+  const v = answer.validation;
+  const checked = v.from === "package" ? `@intentius/sql-yodeler ${v.sqlYodeler}'s schemas` : `behold's pinned copy of SQL Yodeler's schemas (${v.commit})`;
+  const what = answer.report ? `${answer.report.file}, generated ${clock(answer.report.generatedAt, now)}, ${ago(answer.report.generatedAt, now)}` : "no report";
+  return { text: `SQL Yodeler, not live · ${what} · ${answer.drift.length} drift file${answer.drift.length === 1 ? "" : "s"}`, title: `Read from ${answer.source}, checked against ${checked}. behold never runs yodel or reads the database.` };
+}
+
+// #537: the report's audit entries. Each is dated by its own `at` and says
+// where SQL Yodeler read it: a gate ledger on chant/lifecycle, or a row of
+// the environment's history table.
+const AUDIT_WORDS = {
+  "approval-requested": "approval asked",
+  approved: "approved",
+  override: "overridden",
+  silenced: "silenced",
+  applied: "applied",
+  refused: "refused",
+  failed: "failed",
+  repaired: "repaired",
+  reverted: "reverted",
+  step: "step",
+};
+
+/** Where an entry came from: "ledger <l>, <op>/<gate>" or "<history> row <seq>, run <run>". */
+export function auditSource(a) {
+  const s = a.source || {};
+  if (s.ledger !== undefined) return `chant/lifecycle ledger ${s.ledger}, ${s.op}/${s.gate}`;
+  if (s.history !== undefined) return `${s.history} row ${s.seq}, run ${s.run}`;
+  return "an unnamed source";
+}
+
+/** One entry as a line and its source line. Pure. */
+export function auditLines(a, now = new Date()) {
+  const what = [AUDIT_WORDS[a.kind] || a.kind, a.migration || "", a.by ? `by ${a.by}` : ""].filter(Boolean).join(" ");
+  const extra = [a.detail || "", a.digest ? `plan ${String(a.digest).replace(/^(jcs1-)?sha256:/, "").slice(0, 12)}` : "", a.wave ? `wave gate ${a.wave.gate} ${a.wave.status === "approved" ? "approved" : "needed no approval"}` : ""].filter(Boolean);
+  return {
+    text: `${what}${extra.length ? ` (${extra.join(", ")})` : ""} · ${clock(a.at, now)}, ${ago(a.at, now)}`,
+    source: `from ${auditSource(a)}, in ${a.file}`,
+  };
+}

package/web/yodel-report.test.js

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { readYodelReport, yodelValidator } from "../src/yodel-report.ts";
+import { cardsFor, joinMarks, markLine } from "./yodel-report.js";
+
+const fx = join(import.meta.dirname, "..", "src", "__fixtures__", "yodel-report");
+
+describe("yodel report marks on cards (#526)", () => {
+  it("places drift on the example's table cards and lists the rest", () => {
+    const r = readYodelReport(join(fx, "good"), yodelValidator([]));
+    const j = joinMarks(r, ["shop/orders", "shop/shopSchema"]);
+    expect(Object.keys(j.cards)).toEqual(["shop/orders"]);
+    expect(j.unmatched.map((m) => m.object)).toEqual(["ordersStatusIdx"]);
+    expect(cardsFor("orders", ["orders", "x/orders", "ordersX"])).toEqual(["orders", "x/orders"]);
+    expect(markLine(j.cards["shop/orders"][0], new Date("2026-10-11T10:00:00Z"))).toContain("prod: changed out of band (columns[2].default) · drift-prod.json, written");
+  });
+
+});