@intentius/behold 0.14.0 → 0.16.0

package/web/app.js

@@ -52,6 +52,10 @@ import { hasPlayhead, renderPlayhead, waitingFor } from "./run-playhead.js";
 // records a fact for the next tick rather than releasing anything. Same split as
 // the playhead — the decisions are pure in there, the fetches stay here.
 import { hasOperator, renderOperator, APPROVED_SEMANTICS } from "./operator.js";
+// #165: the recorded release on a component — which run put it here, from
+// which commit, approved by whom — and, when the ledger's run id cannot be
+// followed, the reason in words rather than a guessed link.
+import { releaseRows } from "./release.js";
 initTheme();
 initPanel();
 mountThemePicker(document.getElementById("panel-theme"));
@@ -314,10 +318,36 @@ function shortDigest(d) {
  * declared → live form the field-drift section uses for a k8s resource.
  * Provenance comes last: which bytes were compared, and where they came from.
  */
+/** The identity axis (chant#2031) in one sentence — what the observed release
+ * was deployed from, compared to what this project renders. */
+function renderIdentityText(i) {
+  const o = i.observed || {};
+  const d = i.declared || {};
+  switch (i.match) {
+    case "content":
+      return `this render, byte for byte — content ${shortDigest(o.contentDigest)} matches`;
+    case "input":
+      return `this render's inputs — input digest ${shortDigest(o.inputDigest)} matches (bytes may differ per cluster)`;
+    case "mismatch":
+      return o.contentDigest && d.contentDigest
+        ? `a different render — the release records content ${shortDigest(o.contentDigest)}, this project renders ${shortDigest(d.contentDigest)}`
+        : `different inputs — the release records input ${shortDigest(o.inputDigest)}, this project renders ${shortDigest(d.inputDigest)}`;
+    case "unrecorded":
+      return "unknown — no release record names this deploy's render (deployed outside the recorded path, or the ledger could not be read)";
+    case "unpinned":
+      return "not comparable — this render is unpinned, so it has no identity to compare";
+    default:
+      return i.match;
+  }
+}
+
 function renderDriftSection(section, r) {
   const rd = section("render diff");
   rd("verdict", RENDER_VERDICT_LABEL[r.verdict] || r.verdict);
   if (r.reason) rd("reason", RENDER_UNOBSERVED_LABEL[r.reason] || r.reason);
+  // chant#2031: whether what runs was deployed from this render at all — the
+  // question the live diff cannot ask, answered from two recorded digests.
+  if (r.identity) rd("deployed from", renderIdentityText(r.identity));
   if (r.counts) {
     const c = r.counts;
     rd(
@@ -410,6 +440,10 @@ function inspect(node) {
     if (a.status) id("release status", a.status);
     if (a.revision) id("revision", a.revision);
     if (a.chart) id("chart", a.chart);
+    // The deploy's recorded render identity, read back off the ledger
+    // (chant#2031, chant ≥ 0.54.0). Absent for a release no record names.
+    if (a.inputDigest) id("input digest", shortDigest(a.inputDigest));
+    if (a.contentDigest) id("content digest", shortDigest(a.contentDigest));
   }
   // chant#1168 (#1089): `_unobserved` carries WHY chant couldn't read this
   // entity's live state — only ever set alongside the entity overlay's
@@ -542,8 +576,66 @@ function inspect(node) {
     }
   }
 
+  // chant#2040: the Terraform address this chant entity was carved out of —
+  // the manifest names the file, `chant graph` names the file, and the join is
+  // a byte comparison (src/carve-manifest.ts `joinCarvedSources`).
+  const carve = node.attrs && node.attrs._carve;
+  if (carve) {
+    const cf = section("carved from");
+    cf("terraform", carve.tfType ? `${carve.target} (${carve.tfType})` : carve.target);
+    cf("stage", carve.graduated ? "graduated — chant owns it" : `${carve.stage} — Terraform still owns it`);
+    if (carve.at) cf("at", carve.at);
+    if (carve.from) cf("estate", carve.from);
+    cf("emitted as", carve.file);
+  }
+
+  // chant#2022: what an Op step touches in the estate, as the op.json states it
+  // and as the lens resolved it — a resolved value names the card it joined
+  // to; an unresolved one is stated as such, never guessed at (src/ops-lens.ts
+  // `joinStepEntities`).
+  const entityLinks = node.attrs && node.attrs._entityLinks;
+  if (entityLinks) {
+    const touches = section("touches");
+    for (const r of entityLinks.resolved || []) touches(r.value, `${r.node} (${r.via === "id" ? "by id" : "by attribute value"})`);
+    for (const v of entityLinks.unresolved || []) touches(v, "no estate node carries this value — not linked");
+  }
+  // The other end of the same edge: an estate card copied into the ops lens
+  // because a step names it.
+  const touchedBy = node.attrs && node.attrs._touchedBy;
+  if (Array.isArray(touchedBy) && touchedBy.length) {
+    const by = section("touched by");
+    for (const step of touchedBy) by("step", step);
+  }
+
+  // The recorded release (#165, #61's second clause): the ledger row behold
+  // reads on `chant components status` and, until now, read past. Its own
+  // section beside "live status", because the two answer different questions
+  // — what is running versus what was recorded putting it there — and the
+  // reconciliation verdict above is exactly their comparison. The run is a link
+  // only when the record itself carries an address (chant#2045); a bare id
+  // gets its reason, never a guessed forge (web/release.js).
+  const release = node.attrs && node.attrs._release;
+  if (release) {
+    const rel = section("release");
+    for (const [k, v] of releaseRows(release)) {
+      if (v && typeof v === "object" && v.href) {
+        const a = document.createElement("a");
+        a.href = v.href;
+        a.textContent = v.text;
+        a.target = "_blank";
+        a.rel = "noreferrer noopener";
+        a.title = `${v.href} — the address the release record itself carries (chant#2045). behold never invents this link.`;
+        rel(k, a);
+      } else {
+        rel(k, v);
+      }
+    }
+  }
+
   // Declared attributes — the source-of-truth values / cross-resource refs.
-  const attrKeys = Object.keys(node.attrs || {}).filter((k) => !k.startsWith("_"));
+  // The `release` chip is the card's abbreviation of the section above, not a
+  // declared value, so it stays out of this list when the section rendered.
+  const attrKeys = Object.keys(node.attrs || {}).filter((k) => !k.startsWith("_") && !(k === "release" && release));
   if (attrKeys.length) {
     const decl = section("declared");
     for (const k of attrKeys) decl(k, fmtValue(node.attrs[k]));
@@ -1626,10 +1718,16 @@ function carvePick(node) {
  * the follow-up; this is the honest still frame of it. */
 function markCarvedCards() {
   const svg = document.querySelector("#graph svg");
-  if (!svg || !carvedIds.size) return;
+  if (!svg) return;
+  // chant#2040: a chant node whose declaring file a carve manifest names is
+  // carved out of Terraform — the server joins it as `_carve` on the entity
+  // graph and the overlay, so the same still frame the walkthrough draws also
+  // appears on an ordinary estate that holds manifests.
+  const joined = new Set((lastGraphIr && lastGraphIr.nodes ? lastGraphIr.nodes : []).filter((n) => n.attrs && n.attrs._carve).map((n) => n.id));
+  if (!carvedIds.size && !joined.size) return;
   for (const g of svg.querySelectorAll("[data-node-id]")) {
     const id = g.getAttribute("data-node-id");
-    if (!carvedIds.has(id) || g.querySelector('[data-carved="1"]')) continue;
+    if ((!carvedIds.has(id) && !joined.has(id)) || g.querySelector('[data-carved="1"]')) continue;
     g.classList.add("carved");
     // Measured, not read off attributes: pinhole sizes the card from its
     // content and doesn't always stamp width/height, and a missing attribute
@@ -2263,6 +2361,19 @@ function renderApplyProgress(state) {
   // executor — and says so instead of claiming to be an apply.
   summary.textContent = `${state.kind || "apply"}: ${state.status}`;
   wrap.appendChild(summary);
+  // #165: a dispatched run's own page — the one place an environment
+  // protection rule's approval can be granted. A link, never a button: behold
+  // holds no identity that could clear a forge gate, and must not acquire one.
+  if (state.kind === "pipeline" && state.url) {
+    const a = document.createElement("a");
+    a.href = state.url;
+    a.target = "_blank";
+    a.rel = "noreferrer noopener";
+    a.textContent = `run on the forge — approval, if required, is granted there`;
+    a.style.cssText = "font-size:var(--t-caption)";
+    a.title = state.url;
+    wrap.appendChild(a);
+  }
   for (const w of state.waves) {
     const row = document.createElement("div");
     row.style.cssText = "display:flex;align-items:center;gap:8px;flex-wrap:wrap";
@@ -3372,7 +3483,11 @@ async function load(opts = {}) {
       // and no tier (a tier re-evaluates tier-conditioned source, and an Op's
       // IR was already resolved at build). Sending them anyway would also give
       // a static export a different key per tier for one identical snapshot.
-      q = new URLSearchParams({ ops: "1" });
+      // `entities=1` (chant#2022): link each step to the estate cards its
+      // contract-declared entity args name. It is the one thing on the ops
+      // branch that may read a member IR (through the cache the graph above
+      // already warmed), so it is asked for explicitly rather than implied.
+      q = new URLSearchParams({ ops: "1", entities: "1" });
       // #284 item 2: this is the view run state paints over, so this is when
       // it's worth shelling chant for the one thing the record stream can't
       // carry — whether a gate is pending. Asked once per lens load; the
@@ -3648,9 +3763,10 @@ function bringUpSubstrate(s) {
 // login. The server refuses honestly (no gh, unauthenticated, no matching
 // workflow_dispatch workflow) and the reason lands as a toast. Shared by the
 // Substrates tab's button and the ⌘K entry.
-function dispatchPipeline() {
-  if (!window.confirm("Dispatch the GitHub Actions pipeline?\nRuns via YOUR gh login (gh workflow run); behold follows the run on the dial.")) return;
-  fetch("/api/ci/dispatch", { method: "POST" })
+function dispatchPipeline(env) {
+  const target = env || view.env || opsInitialEnv;
+  if (!window.confirm(`Dispatch the GitHub Actions pipeline${target ? ` for ${target}` : ""}?\nRuns via YOUR gh login (gh workflow run); behold follows the run on the dial.`)) return;
+  fetch(`/api/ci/dispatch${target ? `?env=${encodeURIComponent(target)}` : ""}`, { method: "POST" })
     .then((r) => r.json())
     .then((j) => {
       if (j.error) {
@@ -4020,6 +4136,14 @@ function paletteRollback() {
   openRollback(rb);
 }
 
+// #165: per-env executor designations, off /api/project. A designated env's
+// Deploy dispatches the forge workflow instead of running chant here; a
+// designation behold cannot honour disables Deploy with its reason.
+let executorInfo = {};
+function designatedFor(env) {
+  return env && executorInfo && executorInfo[env] ? executorInfo[env] : null;
+}
+
 // Deploy/ops state for the ⌘K palette (#73) — populated once in initActions(),
 // which used to turn each of these straight into a toolbar button. previewMode
 // (declared above, near view) is what the palette gates on: it hides exactly
@@ -4047,6 +4171,9 @@ async function initActions() {
   // lock that hides the git/PR ops.
   const project = await apiFetch("/api/project").then((r) => r.json()).catch(() => ({}));
   opsInitialEnv = project.currentEnv || null;
+  // #165: which envs deploy through a forge, and whether Deploy can dispatch
+  // them right now (`/api/project`'s executor block).
+  executorInfo = project.executor || {};
   previewMode = staticMode || !!project.previewMode; // static ⇒ read-only, no writes at all
   const { ops, adoptLexicons, autoSync, local, applyProgress: apInit, runState: runInit, operatorState: opInit } = await apiFetch("/api/ops")
     .then((r) => r.json())
@@ -4108,7 +4235,27 @@ async function initActions() {
   // the button says Deploy whether the project routes it through a committed
   // ApplyOp or a raw `chant run --components` — the tooltip carries the
   // mechanism.
-  if (opsApply && !previewMode) {
+  const deployEnv = view.env || opsInitialEnv;
+  const designated = designatedFor(deployEnv);
+  if (designated && !previewMode) {
+    // #165: the env deploys through a forge. One button, the forge's name on
+    // it, dispatching the DESIGNATED workflow through the operator's own gh —
+    // and disabled, with the reason, when the designation cannot be honoured.
+    // Never the local button: falling back is what the contract forbids.
+    const forge = { github: "GitHub Actions", gitlab: "GitLab CI", forgejo: "Forgejo" }[designated.forge] || designated.forge || "the forge";
+    const deploy = button(`▶ Deploy via ${forge}`, "", () => dispatchPipeline(deployEnv));
+    if (!designated.ok) {
+      deploy.disabled = true;
+      deploy.title = `Deploy is disabled for ${deployEnv}: ${designated.reason}`;
+    } else {
+      deploy.title = `gh workflow run ${designated.workflow} — ${deployEnv} deploys through ${forge} per .behold.json. behold dispatches through YOUR gh and follows the run on the dial; any approval the workflow's environment requires is granted on the forge, not here.`;
+    }
+    bar.appendChild(deploy);
+    const note = document.createElement("span");
+    note.style.cssText = "color:var(--muted);font-size:var(--t-caption);align-self:center";
+    note.textContent = designated.ok ? `${deployEnv}: approval, if any, lives on ${forge}` : `${deployEnv}: ${designated.reason}`;
+    bar.appendChild(note);
+  } else if (opsApply && !previewMode) {
     const deploy = button(`▶ Deploy (${opsApply.name})`, "", () => {
       if (window.confirm(`Run the committed ApplyOp "${opsApply.name}"?\nDelegated write: behold triggers, chant's executor applies.`)) runOp(opsApply.name);
     });
@@ -4327,17 +4474,25 @@ function paletteCommands() {
   // renderSubstrates()'s previous button-gating precisely.
   if (!previewMode) {
     if (opsApply) {
-      c.push([`Deploy: Sync (${opsApply.name})`, () => runOp(opsApply.name)]);
+      // #165: not for a designated env — its ApplyOp is refused server-side too.
+      if (!designatedFor(view.env || opsInitialEnv)) c.push([`Deploy: Sync (${opsApply.name})`, () => runOp(opsApply.name)]);
       if (opsApply.gate) c.push([`Approve ${opsApply.gate}`, () => signal(opsApply.name, opsApply.gate)]);
     }
-    c.push(["Rollback to a prior revision…", () => paletteRollback()]);
+    // #165: a designated env's applies happen on the forge, so a rollback PR
+    // opened from here would have nothing local to land — hidden, as designed.
+    if (!designatedFor(view.env || opsInitialEnv)) c.push(["Rollback to a prior revision…", () => paletteRollback()]);
     for (const op of opsRunnable) {
       c.push([`Run: ${op.name}`, () => { if (window.confirm(`Run Op "${op.name}"?`)) runOp(op.name); }]);
     }
   }
   // No committed ApplyOp, but there's an env → "Apply all" is the equivalent
   // deploy action (M3) — stays available in preview (a local write, not git/PR).
-  if (!opsApply && opsInitialEnv) c.push([`Deploy: Apply all → ${opsInitialEnv}`, () => confirmApplyAll()]);
+  if (!opsApply && opsInitialEnv && !designatedFor(opsInitialEnv)) c.push([`Deploy: Apply all → ${opsInitialEnv}`, () => confirmApplyAll()]);
+  // #165: a designated env deploys through its forge, from the palette too.
+  if (designatedFor(view.env || opsInitialEnv) && !previewMode) {
+    const d = designatedFor(view.env || opsInitialEnv);
+    if (d.ok) c.push([`Deploy via ${d.forge} → ${view.env || opsInitialEnv}`, () => dispatchPipeline(view.env || opsInitialEnv)]);
+  }
 
   for (const s of lastSubstrates) {
     if (s.bringUp) c.push([`Bring up ${s.label}`, () => bringUpSubstrate(s)]);

package/web/release.js

@@ -0,0 +1,66 @@
+// #165 (#61's second clause): the recorded release, read off a component
+// node's `_release` attr (src/component-status.ts's `releaseStatus`). The pure
+// half, tested the way web/operator.js and web/run-playhead.js are — no DOM.
+// The card chip (`release`) already answers "which commit, through what"; this
+// is the pane's fuller answer — which run, from which commit, approved by whom
+// — and, when the record cannot be followed, the reason in words.
+import { approvalLink } from "./operator.js";
+import { waitingFor } from "./run-playhead.js";
+
+/** How the pane names each id space. `laptop` for a local mint: "local" would
+ * read as a place, and the point is that there is nowhere to go. */
+export const FORGE_LABEL = { github: "GitHub Actions", gitlab: "GitLab CI", op: "an Op run", local: "a laptop run", unknown: "an unlinked run" };
+
+/** The one line that says why there is no link, or null when there is one.
+ * Never a placeholder link, never a guessed forge: the three id spaces a
+ * `runId` can live in are mutually incompatible, so a link behold built from
+ * a bare id would as often be wrong as right (chant#2045). */
+export function unlinkedReason(release) {
+  if (!release) return null;
+  if (runLink(release)) return null;
+  switch (release.forge) {
+    case "local":
+      return release.originSource === "record"
+        ? "minted on the machine that deployed — the record says so; there is no run to open"
+        : "minted on the machine that deployed (a local- id) — there is no run to open";
+    case "unknown":
+      return "the record names a run id and nothing else — no forge, no repo, no URL. A chant older than chant#2045 wrote it; behold will not guess which forge the id belongs to";
+    case "op":
+      return "an orchestrator run id — the run lives in Temporal, not on a forge";
+    default:
+      return `${FORGE_LABEL[release.forge] || release.forge} named no server URL when this was recorded, so the id cannot be resolved to a link`;
+  }
+}
+
+/** The run's absolute http(s) URL, or null. Same validator as the gate card's
+ * `approve at:` — an address the ledger itself carries, or nothing. */
+export function runLink(release) {
+  return release && release.originSource === "record" ? approvalLink(release.url) : null;
+}
+
+/** `<runId> (<forge>)` — the run row's text, link or no link. */
+export function runText(release) {
+  const forge = FORGE_LABEL[release.forge] || release.forge;
+  return release.repo ? `${release.runId} · ${forge} · ${release.repo}` : `${release.runId} · ${forge}`;
+}
+
+/** The pane's rows, in order: `[key, value]` pairs plus an optional caveat
+ * row keyed `""`. The link is returned as `{href, text}` so the DOM half makes
+ * the anchor and this half stays testable. */
+export function releaseRows(release, now = Date.now()) {
+  if (!release) return [];
+  const rows = [];
+  const href = runLink(release);
+  rows.push(["run", href ? { href, text: runText(release) } : runText(release)]);
+  const why = unlinkedReason(release);
+  if (why) rows.push(["", why]);
+  rows.push(["commit", release.gitSha]);
+  rows.push(["digest", release.digest]);
+  const ago = release.timestamp ? waitingFor(release.timestamp, now) : null;
+  rows.push(["recorded", ago ? `${release.timestamp} (${ago} ago)` : release.timestamp]);
+  rows.push(["actor", release.actor]);
+  // Absent means ungated — chant omits `approver` exactly then — so the row
+  // says that rather than leaving a gap the reader could take for a redaction.
+  rows.push(["approver", release.approver || "none — an ungated change"]);
+  return rows;
+}

package/web/release.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { releaseRows, runLink, unlinkedReason, runText } from "../web/release.js";
+
+const NOW = Date.parse("2026-09-01T12:00:00Z");
+const base = { runId: "18234771902", gitSha: "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678", digest: "sha256:86bf5e3c", timestamp: "2026-09-01T11:30:00Z", actor: "ci-bot" };
+
+describe("release rows (#165)", () => {
+  it("a record that carries its own address links the run, and names forge + repo", () => {
+    const r = { ...base, forge: "github", originSource: "record", repo: "INTENTIUS/loomster", url: "https://github.com/INTENTIUS/loomster/actions/runs/18234771902", approver: "alex" };
+    const rows = releaseRows(r, NOW);
+    expect(rows[0]).toEqual(["run", { href: r.url, text: "18234771902 · GitHub Actions · INTENTIUS/loomster" }]);
+    expect(rows.find(([k]) => k === "")).toBeUndefined();
+    expect(rows.find(([k]) => k === "approver")[1]).toBe("alex");
+    expect(rows.find(([k]) => k === "recorded")[1]).toBe("2026-09-01T11:30:00Z (30m ago)");
+  });
+
+  it("a bare id from a pre-chant#2045 record is never linked, and the caveat says why", () => {
+    const r = { ...base, forge: "unknown", originSource: "inferred" };
+    expect(runLink(r)).toBeNull();
+    expect(unlinkedReason(r)).toMatch(/chant#2045/);
+    expect(unlinkedReason(r)).toMatch(/will not guess/);
+    expect(releaseRows(r, NOW)[0]).toEqual(["run", "18234771902 · an unlinked run"]);
+  });
+
+  it("a laptop run says there is nowhere to go — whether the record said local or the id's spelling did", () => {
+    const said = { ...base, runId: "local-1756726200000", forge: "local", originSource: "record" };
+    const spelled = { ...base, runId: "local-1756726200000", forge: "local", originSource: "inferred" };
+    expect(unlinkedReason(said)).toMatch(/the record says so/);
+    expect(unlinkedReason(spelled)).toMatch(/a local- id/);
+    expect(runText(said)).toBe("local-1756726200000 · a laptop run");
+  });
+
+  it("an inferred origin never yields a link even if a url is somehow present", () => {
+    expect(runLink({ ...base, forge: "github", originSource: "inferred", url: "https://example.com/run" })).toBeNull();
+  });
+
+  it("a recorded origin with a non-http url is not a link — the gate card's rule", () => {
+    const r = { ...base, forge: "github", originSource: "record", url: "javascript:alert(1)" };
+    expect(runLink(r)).toBeNull();
+    expect(unlinkedReason(r)).toMatch(/named no server URL/);
+  });
+
+  it("an ungated change says so in the approver row rather than leaving a gap", () => {
+    const rows = releaseRows({ ...base, forge: "op", originSource: "record" }, NOW);
+    expect(rows.find(([k]) => k === "approver")[1]).toBe("none — an ungated change");
+    expect(unlinkedReason({ ...base, forge: "op", originSource: "record" })).toMatch(/Temporal/);
+  });
+
+  it("nothing recorded → no rows", () => {
+    expect(releaseRows(undefined)).toEqual([]);
+  });
+});