@intentius/behold 0.14.0 → 0.15.0

package/AGENTS.md

@@ -54,6 +54,13 @@ preview-locked, and one load runs at a time (409 otherwise).
    per-node observed state, drift and field ownership; `/api/reconcile?env=`
    summarizes the pending change set; `/api/substrates` reports substrate
    readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`.
+   With `?components=1&env=`, each component node carries `_liveStatus` (the
+   `chant components status` verdict) and, when the release ledger recorded
+   one, `_release` — `{runId, forge, originSource, url?, gitSha, digest,
+   timestamp, actor, approver?}` (#165). `url` is present only when the record
+   itself carries an address (chant#2045); `originSource: "inferred"` means
+   behold read the id's spelling and nothing more, and a `forge: "unknown"` id
+   is never resolved to a link on behold's guess.
    `?ops=1` is the ops lens — the project's declared Ops as a phase track, read
    from each emitted `dist/ops/<name>/op.json`, with the current run painted
    over it (`meta.run`, `meta.gate`); `/api/ops/<name>/status` reads that Op's
@@ -257,3 +264,39 @@ own Terraform is not edited either. The only request-derived value is `select`,
 and it must be an address the served report already ranks — the value that
 reaches the spawn's argv comes from a closed set read off disk. No cloud write,
 no Terraform mutation, no edit to anyone's chant source.
+
+## Changing behold (for agents working on this repo)
+
+The sections above are about driving a running behold. This one is about
+changing it — the working rules that used to live in a handoff note and now
+live here, with the enforceable ones enforced.
+
+- **Branches and merges.** Work on a branch off `main` (an isolated worktree
+  when more than one agent is active). `main` is protected by a ruleset: every
+  change arrives as a PR, and the `check` job in `ci.yml` must be green before
+  it merges. A check that has merely settled is not a pass — read the lines.
+  No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
+  next onto what landed.
+- **The local gate** is `just check` (tsc, tests, build). `just test` keeps
+  the reporter's full output in `vitest.log`, because #334's one-shot
+  first-run failures kept losing the failing file's name — if the suite fails
+  once and passes on rerun, the log from the first run is the evidence; attach
+  it to #334.
+- **Releasing** is `just release`, after the version-bump PR merged: it tags
+  `behold-v<version>`, pushes the tag (which is what runs `release.yml`), and
+  waits for npm to show the version. It refuses in every state where a tag
+  push would be wrong. Never re-push a `behold-v*` tag by hand — a tag push
+  re-fires publish. Tags absent from origin (behold-v0.10.0, 0.10.1) stay
+  absent for that reason.
+- **Scratch infrastructure** is governed by `src/scratch.ts`, asserted by
+  `scratch.test.ts` across every boot site: anything behold boots is named
+  `behold-*`, refuses if the name is taken, tears down only what it created,
+  and never binds the shared emulator ports. The protected names — `floci*`,
+  `chant-floci*`, the kubemicrovm and fountain k3d clusters, :4566 — are
+  listed there, not in prose. A new boot site calls `assertScratch` before
+  its spawn and gets a row in the test.
+- **The write boundary** is the Invariant section above. Apply is never a
+  button; `/api/carve/apply` does not exist and the route test asserts it
+  stays that way.
+- **chant's working rules** (its single-lane checkout, its release path) are
+  chant's and live in chant's repo, not here.

package/dist/cli.js

@@ -2871,6 +2871,50 @@ function componentStatusColor(row) {
       return "neutral";
   }
 }
+function httpUrl(url) {
+  if (typeof url !== "string" || !url) return void 0;
+  try {
+    const p = new URL(url);
+    return p.protocol === "http:" || p.protocol === "https:" ? url : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function releaseOrigin(rec6) {
+  const origin = rec6.runOrigin;
+  if (origin && typeof origin.forge === "string") {
+    const url = httpUrl(origin.url);
+    return {
+      forge: origin.forge,
+      originSource: "record",
+      ...origin.repo ? { repo: origin.repo } : {},
+      ...url ? { url } : {}
+    };
+  }
+  return { forge: rec6.runId.startsWith("local-") ? "local" : "unknown", originSource: "inferred" };
+}
+var FORGE_WORD = {
+  github: "github",
+  gitlab: "gitlab",
+  op: "op",
+  local: "laptop",
+  unknown: "?"
+};
+function releaseChip(status) {
+  return `${status.gitSha.slice(0, 7)} via ${FORGE_WORD[status.forge]}`;
+}
+function releaseStatus(rec6) {
+  if (!rec6) return void 0;
+  return {
+    runId: rec6.runId,
+    ...releaseOrigin(rec6),
+    gitSha: rec6.gitSha,
+    digest: rec6.digest,
+    timestamp: rec6.timestamp,
+    actor: rec6.actor,
+    ...rec6.approver ? { approver: rec6.approver } : {}
+  };
+}
 function joinComponentStatus(ir, rows) {
   const byComponent = new Map(rows.map((r) => [r.component, r]));
   return {
@@ -2878,10 +2922,12 @@ function joinComponentStatus(ir, rows) {
     nodes: ir.nodes.map((n) => {
       const row = byComponent.get(n.id);
       if (!row) return n;
+      const release = releaseStatus(row.recorded);
       return {
         ...n,
         attrs: {
           ...n.attrs,
+          ...release ? { release: releaseChip(release), _release: release } : {},
           _status: componentStatusColor(row),
           _liveStatus: {
             reconciliation: row.reconciliation,
@@ -6595,6 +6641,34 @@ function reanchorEdges(svg, moved) {
 import { spawn as spawn3 } from "node:child_process";
 import { readFileSync as readFileSync9, writeFileSync as writeFileSync3, existsSync as existsSync7 } from "node:fs";
 import { join as join12 } from "node:path";
+
+// src/scratch.ts
+var PROTECTED_INFRA = [
+  /^floci(-|$)/,
+  /^chant-floci(-|$)/,
+  /^k3d-kubemicrovm-local$/,
+  /^k3d-fountain-local$/,
+  /^kubemicrovm-local$/,
+  /^fountain-local$/
+];
+var PROTECTED_PORTS = [4566, 4577, 4588];
+var SCRATCH_PREFIX = "behold-";
+function scratchNameProblem(name) {
+  if (!name.startsWith(SCRATCH_PREFIX)) return `scratch infra must be named ${SCRATCH_PREFIX}*, got ${JSON.stringify(name)}`;
+  const hit = PROTECTED_INFRA.find((re) => re.test(name));
+  if (hit) return `${JSON.stringify(name)} is protected infrastructure (${hit}) \u2014 behold never touches it`;
+  return void 0;
+}
+function scratchPortProblem(port) {
+  if (PROTECTED_PORTS.includes(port)) return `port ${port} belongs to a shared emulator \u2014 a scratch substrate gets its own`;
+  return void 0;
+}
+function assertScratch(name, port) {
+  const p = scratchNameProblem(name) ?? (port === void 0 ? void 0 : scratchPortProblem(port));
+  if (p) throw new Error(`scratch discipline: ${p}`);
+}
+
+// src/carve-live.ts
 var LIVE_CONTAINER = "behold-carve-floci";
 var LIVE_PORT = 4602;
 var LIVE_IMAGE = "floci/floci:1.5.34";
@@ -6627,6 +6701,7 @@ function capture(cmd, args, cwd) {
   });
 }
 async function bootScratchFloci() {
+  assertScratch(LIVE_CONTAINER, LIVE_PORT);
   const ps = await capture("docker", ["ps", "-a", "--format", "{{.Names}}"], process.cwd());
   if (ps.code !== 0) return "docker isn't answering \u2014 is the daemon up?";
   if (ps.stdout.split("\n").includes(LIVE_CONTAINER)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/behold",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "behold — a live control plane on chant. See your whole estate (every substrate in one graph), coloured by drift; act through delegated, gated Ops.",
   "bin": {

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"));
@@ -542,8 +546,35 @@ function inspect(node) {
     }
   }
 
+  // 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]));

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([]);
+  });
+});