@intentius/behold 0.29.40 → 0.29.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/AGENTS.md +148 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +15965 -13076
  4. package/example-writes/README.md +1 -1
  5. package/example-writes/chant.config.ts +0 -6
  6. package/package.json +5 -2
  7. package/web/app.js +327 -21
  8. package/web/carve-export.js +142 -0
  9. package/web/carve-narration.js +268 -0
  10. package/web/carve-narration.test.js +18 -0
  11. package/web/change-set-overlay.js +147 -0
  12. package/web/change-set-overlay.test.js +83 -0
  13. package/web/dots-border.js +66 -0
  14. package/web/dots-border.test.js +27 -0
  15. package/web/dots-kiosk.js +279 -0
  16. package/web/dots-kiosk.test.js +60 -0
  17. package/web/dots-layout.d.ts +10 -0
  18. package/web/dots-layout.js +201 -0
  19. package/web/dots-live.js +316 -0
  20. package/web/dots-live.test.js +220 -0
  21. package/web/dots-lod.js +122 -0
  22. package/web/dots-lod.test.js +78 -0
  23. package/web/dots-recording.d.ts +7 -0
  24. package/web/dots-recording.js +247 -0
  25. package/web/dots-recording.test.js +71 -0
  26. package/web/dots-scene.js +294 -0
  27. package/web/dots-scene.test.js +118 -0
  28. package/web/dots-timeline.js +128 -0
  29. package/web/dots-timeline.test.js +83 -0
  30. package/web/dots-tour.js +153 -0
  31. package/web/dots.js +2124 -0
  32. package/web/dots.test.js +15 -0
  33. package/web/index.html +29 -0
  34. package/web/kiosk-carve.js +219 -0
  35. package/web/kiosk-carve.test.js +26 -0
  36. package/web/kiosk-event-help-ui.js +6 -0
  37. package/web/kiosk.js +21 -6
  38. package/web/operator.js +1 -1
  39. package/web/run-playhead.js +102 -19
  40. package/web/run-playhead.test.js +81 -11
  41. package/web/tour-player.js +204 -0
  42. package/web/tour-player.test.js +115 -0
  43. package/web/tours/behold.tour.v1.schema.json +182 -0
  44. package/web/tours/terralith.json +330 -0
  45. package/web/trunk-lane.js +254 -0
  46. package/web/trunk-lane.test.js +117 -0
  47. package/web/workspace-gates.js +29 -4
  48. package/web/workspace-gates.test.js +23 -2
@@ -5,13 +5,13 @@
5
5
  // approve button POSTs) is a function from data to data; the DOM half is
6
6
  // smoke/ui-smoke.mjs's job.
7
7
  import { describe, it, expect } from "vitest";
8
- import { runVerdict, stepRows, gateCardFrom, hasPlayhead, took, waitingFor } from "./run-playhead.js";
8
+ import { runVerdict, stepRows, gateCardFrom, hasPlayhead, took, waitingFor, stepTook, sourceLabel, pointLine, applyChipText, waitingLine } from "./run-playhead.js";
9
9
 
10
10
  const base = {
11
11
  op: "playhead-probe",
12
12
  mode: "temporal",
13
13
  status: "running",
14
- records: [],
14
+ steps: [],
15
15
  gate: null,
16
16
  gateNote: null,
17
17
  startedAt: "2026-08-29T18:00:00.000Z",
@@ -20,7 +20,7 @@ const base = {
20
20
  };
21
21
  const withRecords = (n) => ({
22
22
  ...base,
23
- records: Array.from({ length: n }, (_, i) => ({ phase: "P", fn: `f${i}`, status: "ok", durationMs: 1000 })),
23
+ steps: Array.from({ length: n }, (_, i) => ({ component: null, phase: "P", step: `f${i}`, state: "ok", durationMs: 1000 })),
24
24
  });
25
25
 
26
26
  describe("took", () => {
@@ -48,7 +48,7 @@ describe("waitingFor", () => {
48
48
  describe("runVerdict", () => {
49
49
  it("has nothing to say before anything has run", () => {
50
50
  expect(runVerdict(null)).toBeNull();
51
- expect(runVerdict({ op: null, status: "idle", records: [] })).toBeNull();
51
+ expect(runVerdict({ op: null, status: "idle", steps: [] })).toBeNull();
52
52
  });
53
53
 
54
54
  it("never calls a lost stream finished", () => {
@@ -63,8 +63,16 @@ describe("runVerdict", () => {
63
63
  expect(runVerdict({ ...withRecords(2), status: "failed" }).text).toContain("a step failed");
64
64
  });
65
65
 
66
- it("counts settled steps while a local run streams them (#459: --progress-json)", () => {
67
- expect(runVerdict({ ...withRecords(1), mode: "local" }).text).toContain("running — 1 step settled");
66
+ it("counts settled steps while a local run streams them, not the one running (#679)", () => {
67
+ const run = { ...withRecords(1), steps: [...withRecords(1).steps, { component: null, phase: "P", step: "g", state: "running" }] };
68
+ expect(runVerdict(run).text).toContain("running, 1 step settled");
69
+ expect(runVerdict({ ...run, following: true }).text).toContain("running (followed)");
70
+ });
71
+
72
+ it("says a run waiting on a decision point waits on a person, not that it failed (#679)", () => {
73
+ const v = runVerdict({ ...withRecords(1), status: "waiting" });
74
+ expect(v.text).toContain("waiting on a decision point");
75
+ expect(v.tone).toBe("waiting");
68
76
  });
69
77
 
70
78
  it("says a gated run stopped at its gate and runs again after approval (#459)", () => {
@@ -84,10 +92,10 @@ describe("runVerdict", () => {
84
92
  describe("stepRows", () => {
85
93
  it("keeps arrival order and labels a skip as a skip, not a duration", () => {
86
94
  const rows = stepRows({
87
- records: [
88
- { phase: "Build", fn: "chantBuild", status: "ok", durationMs: 1062 },
89
- { phase: "Verify", fn: "httpCheck", status: "fail", durationMs: 15164, error: "fetch failed" },
90
- { phase: "Never", fn: "httpCheck", status: "skipped", durationMs: 0 },
95
+ steps: [
96
+ { component: null, phase: "Build", step: "chantBuild", state: "ok", durationMs: 1062 },
97
+ { component: null, phase: "Verify", step: "httpCheck", state: "failed", durationMs: 15164, error: "fetch failed" },
98
+ { component: null, phase: "Never", step: "httpCheck", state: "skipped", durationMs: 0 },
91
99
  ],
92
100
  });
93
101
  expect(rows.map((r) => `${r.label} ${r.took}`)).toEqual([
@@ -135,7 +143,69 @@ describe("gateCardFrom", () => {
135
143
  describe("hasPlayhead", () => {
136
144
  it("is false on a fresh session and true once an Op is being watched", () => {
137
145
  expect(hasPlayhead(null)).toBe(false);
138
- expect(hasPlayhead({ op: null, records: [] })).toBe(false);
146
+ expect(hasPlayhead({ op: null, steps: [] })).toBe(false);
139
147
  expect(hasPlayhead(base)).toBe(true);
140
148
  });
141
149
  });
150
+
151
+ // #679: every state chant's run events report, as it happens.
152
+ describe("stepTook", () => {
153
+ it("reads each state chant reports, and says why a step skipped", () => {
154
+ expect(stepTook({ state: "running" })).toBe("running");
155
+ expect(stepTook({ state: "ok", durationMs: 6 })).toBe("6ms");
156
+ expect(stepTook({ state: "skipped", skip: "receipt" })).toBe("skipped: already applied (receipt)");
157
+ expect(stepTook({ state: "skipped", skip: "not-run" })).toBe("skipped: not run: an earlier step stopped the run (not-run)");
158
+ expect(stepTook({ state: "skipped", skip: null })).toBe("skipped");
159
+ expect(stepTook({ state: "cached", durationMs: 3 })).toBe("cached");
160
+ expect(stepTook({ state: "gated", durationMs: 680 })).toBe("gated");
161
+ expect(stepTook({ state: "waiting" })).toBe("waiting");
162
+ // The older stream's component steps carry no timing.
163
+ expect(stepTook({ state: "ok", durationMs: null })).toBe("ok");
164
+ });
165
+
166
+ it("names the component and who approved a gate on a row", () => {
167
+ const [row] = stepRows({ steps: [{ component: "db", phase: "Apply", step: "gate:approve-db", state: "ok", durationMs: 40, approvedBy: "alex" }] });
168
+ expect(row.label).toBe("db · Apply · gate:approve-db");
169
+ expect(row.approvedBy).toBe("alex");
170
+ });
171
+ });
172
+
173
+ describe("sourceLabel", () => {
174
+ it("labels the classifier path best-effort, and a degraded run with the server's reason", () => {
175
+ expect(sourceLabel("classifier").text).toMatch(/^best-effort: chant did not run this pipeline/);
176
+ expect(sourceLabel("classifier").text).toContain("only the exit code is certain");
177
+ expect(sourceLabel("progress", "degraded: this project's chant (0.124.24) is older than 0.124.28").text).toContain("0.124.24");
178
+ expect(sourceLabel("progress").text).toMatch(/^degraded/);
179
+ expect(sourceLabel("events").text).toBe("from chant's run events");
180
+ expect(sourceLabel("forge").text).toContain("forge");
181
+ expect(sourceLabel(undefined)).toBeNull();
182
+ expect(sourceLabel(null, "a steward run keeps no events on this host").text).toContain("steward");
183
+ });
184
+ });
185
+
186
+ describe("pointLine", () => {
187
+ it("names a decision point and the command that answers it", () => {
188
+ expect(pointLine({ point: { id: "pt-1", since: "2026-10-17T04:24:48.329Z" } })).toBe(
189
+ "waiting on decision point pt-1 since 2026-10-17T04:24:48.329Z; answer it with chant workspace points answer pt-1",
190
+ );
191
+ expect(pointLine({ point: null })).toBeNull();
192
+ });
193
+ });
194
+
195
+ describe("applyChipText", () => {
196
+ it("shows the step a component is on and how it stands, as it happens", () => {
197
+ expect(applyChipText("loom-db", { status: "running", phase: "Apply", step: "cfn-deploy", stepState: "running" })).toBe("loom-db · Apply · cfn-deploy (running)");
198
+ expect(applyChipText("sf", { status: "ok", phase: "Apply", step: "cfn-deploy", stepState: "skipped", skip: "receipt" })).toBe("sf · Apply · cfn-deploy skipped: already applied (receipt) (ok)");
199
+ expect(applyChipText("sf", { status: "running", phase: "Apply", step: "cfn-outputs", stepState: "cached" })).toBe("sf · Apply · cfn-outputs cached (running)");
200
+ expect(applyChipText("db", { status: "gated", phase: "Apply", step: "gate:approve-db", stepState: "gated" })).toBe("db · Apply · gate:approve-db (gated)");
201
+ expect(applyChipText("db", { status: "pending" })).toBe("db (pending)");
202
+ });
203
+ });
204
+
205
+ describe("waitingLine", () => {
206
+ it("names the gate or decision point a component run waits on", () => {
207
+ expect(waitingLine({ gate: "approve-db", point: null, component: "loom-db", since: "t" })).toBe("waiting on gate approve-db (loom-db) since t");
208
+ expect(waitingLine({ gate: null, point: "pt-1", component: null, since: "t", message: "which region?" })).toBe("waiting on decision point pt-1 since t: which region?");
209
+ expect(waitingLine(null)).toBeNull();
210
+ });
211
+ });
@@ -0,0 +1,204 @@
1
+ // The tour player (behold.tour/v1): which chapter of a tour a cycle is in,
2
+ // and which of its visuals are on, from the events that have happened. Pure:
3
+ // the tour and an event stream in, plain data out, so the live carve and a
4
+ // recorded cycle or bundle can feed it the same way.
5
+ //
6
+ // An event is one of:
7
+ // { kind: "beat", beat, step, at } demo.json's beat and step
8
+ // { kind: "line", migration, line, at } a migration's first or last progress line
9
+ // { kind: "wave", wave, edge, at } a wave's job starting or ending
10
+ // `at` is a time in ms. A trigger matches an event of its kind whose fields
11
+ // equal the trigger's; `after_at` (a named run's finish, which the server
12
+ // resolves) keeps out an event at or before it, and `blocked` (the named run
13
+ // does not exist yet) matches nothing.
14
+ //
15
+ // The current chapter is the last chapter, in the file's order, whose trigger
16
+ // has fired by `t`: a cycle's beats only go forward, so a later chapter that
17
+ // fired wins over an earlier one that fired since.
18
+
19
+ const has = (o, k) => o && Object.prototype.hasOwnProperty.call(o, k);
20
+
21
+ /** The first event at or before `t` that `trigger` matches, or null. */
22
+ export function firedBy(trigger, events, t = Infinity) {
23
+ if (!trigger || trigger.blocked) return null;
24
+ if (Array.isArray(trigger.any)) {
25
+ let best = null;
26
+ for (const tr of trigger.any) {
27
+ const e = firedBy(tr, events, t);
28
+ if (e && (!best || e.at < best.at)) best = e;
29
+ }
30
+ return best;
31
+ }
32
+ let best = null;
33
+ for (const e of events || []) {
34
+ if (!(e.at <= t)) continue;
35
+ if (!matches(trigger, e)) continue;
36
+ if (!best || e.at < best.at) best = e;
37
+ }
38
+ return best;
39
+ }
40
+
41
+ function matches(tr, e) {
42
+ if (has(tr, "migration")) {
43
+ if (e.kind !== "line" || e.migration !== tr.migration || e.line !== tr.line) return false;
44
+ } else if (has(tr, "wave")) {
45
+ if (e.kind !== "wave" || e.wave !== tr.wave || e.edge !== tr.edge) return false;
46
+ } else {
47
+ if (e.kind !== "beat") return false;
48
+ if (has(tr, "beat") && e.beat !== tr.beat) return false;
49
+ if (has(tr, "step") && e.step !== tr.step) return false;
50
+ }
51
+ if (typeof tr.after_at === "number" && !(e.at > tr.after_at)) return false;
52
+ return true;
53
+ }
54
+
55
+ /**
56
+ * The chapter at `t`: `{ index, chapter, at, progress }`, or null before the
57
+ * first chapter's trigger. `step`: demo.json's step now, for how far a chapter
58
+ * that a beat started has got along the tour's `steps`.
59
+ */
60
+ export function chapterAt(tour, events, t = Infinity, step = null) {
61
+ const chapters = (tour && tour.chapters) || [];
62
+ for (let i = chapters.length - 1; i >= 0; i--) {
63
+ const e = firedBy(chapters[i].trigger, events, t);
64
+ if (e) return { index: i, chapter: chapters[i], at: e.at, progress: progressOf(tour, i, step) };
65
+ }
66
+ return null;
67
+ }
68
+
69
+ /** How far chapter `i` has got, 0..1: the step's place in the tour's steps; the last chapter is whole once reached. */
70
+ export function progressOf(tour, i, step) {
71
+ const chapters = (tour && tour.chapters) || [];
72
+ if (i >= chapters.length - 1) return 1;
73
+ const steps = (tour && tour.steps) || [];
74
+ const k = step ? steps.indexOf(step) : -1;
75
+ if (k < 0 || steps.length < 2) return 0;
76
+ return k / (steps.length - 1);
77
+ }
78
+
79
+ /** Each chapter's place on the rail: done, current (with its progress) or ahead. */
80
+ export function railOf(tour, at) {
81
+ return ((tour && tour.chapters) || []).map((c, i) => ({
82
+ n: i + 1,
83
+ id: c.id,
84
+ title: c.title,
85
+ state: !at ? "ahead" : i < at.index ? "done" : i === at.index ? "current" : "ahead",
86
+ progress: !at ? 0 : i < at.index ? 1 : i === at.index ? at.progress : 0,
87
+ }));
88
+ }
89
+
90
+ /** A chapter's visuals that are on at `t`: those with no `when`, and those whose `when` has fired. Each with `at`, when it fired. */
91
+ export function shownAt(chapter, events, t = Infinity) {
92
+ const out = [];
93
+ for (const s of (chapter && chapter.show) || []) {
94
+ if (!s.when) {
95
+ out.push({ ...s, at: null });
96
+ continue;
97
+ }
98
+ const e = firedBy(s.when, events, t);
99
+ if (e) out.push({ ...s, at: e.at });
100
+ }
101
+ return out;
102
+ }
103
+
104
+ /**
105
+ * A line of text with its facts filled in, or null when a fact it names has
106
+ * no value: a fact with no record behind it is left out, never shown as 0.
107
+ */
108
+ export function fill(text, facts) {
109
+ if (typeof text !== "string") return null;
110
+ let missing = false;
111
+ const out = text.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/g, (_, k) => {
112
+ const v = facts ? facts[k] : undefined;
113
+ if (v === undefined || v === null || v === "") {
114
+ missing = true;
115
+ return "";
116
+ }
117
+ return typeof v === "number" ? v.toLocaleString("en-US") : String(v);
118
+ });
119
+ return missing ? null : out;
120
+ }
121
+
122
+ /** A chapter's lines, filled; a line naming a fact with no record is dropped. */
123
+ export function chapterLines(chapter, facts) {
124
+ return ((chapter && chapter.text) || []).map((l) => fill(l, facts)).filter((l) => l !== null);
125
+ }
126
+
127
+ /** The card's rows, filled; a row with no record is dropped. */
128
+ export function cardRows(card, facts) {
129
+ return (card || []).map((r) => ({ label: r.label, text: fill(r.text, facts) })).filter((r) => r.text !== null);
130
+ }
131
+
132
+ // --- the live badge's lag (faithfulness 3) -----------------------------------
133
+
134
+ /** After this long with no write while a migration runs, the badge says it is waiting for the job. */
135
+ export const LAG_WAIT_MS = 60_000;
136
+
137
+ /**
138
+ * The words beside LIVE: "last write N s ago", from the newest progress
139
+ * line's `at` and the page's clock; "waiting for the job" once the gap passes
140
+ * a minute while a migration runs; null with no write to measure from.
141
+ */
142
+ export function lagText(newestAt, now, running) {
143
+ const at = typeof newestAt === "number" ? newestAt : Date.parse(newestAt || "");
144
+ if (!Number.isFinite(at)) return null;
145
+ const gap = Math.max(0, now - at);
146
+ if (running && gap > LAG_WAIT_MS) return "waiting for the job";
147
+ const s = Math.floor(gap / 1000);
148
+ if (s < 60) return `last write ${s} s ago`;
149
+ const m = Math.floor(s / 60);
150
+ if (m < 60) return `last write ${m} min ago`;
151
+ return `last write ${Math.floor(m / 60)} h ago`;
152
+ }
153
+
154
+ // --- a landed dot's provenance (faithfulness 2) --------------------------------
155
+
156
+ /** A line's time as a reader reads it: UTC, to the millisecond. */
157
+ export function clockOf(at) {
158
+ const d = new Date(typeof at === "number" ? at : Date.parse(at || ""));
159
+ if (Number.isNaN(d.getTime())) return null;
160
+ return `${d.toISOString().slice(11, 23)} UTC`;
161
+ }
162
+
163
+ /**
164
+ * What happened to a landed dot, from its progress line and the migration
165
+ * that wrote it: "live-mv retagged aws_iam_role.x from tl1-terralith to
166
+ * tl1-team-a at 16:57:49.668 UTC · job #3655". `w`: { outcome, address, from,
167
+ * to, at, tool, job, reason }.
168
+ */
169
+ export function provenanceText(w) {
170
+ if (!w || !w.address) return null;
171
+ const when = clockOf(w.at);
172
+ const at = when ? ` at ${when}` : "";
173
+ const job = w.job ? ` · job #${w.job}` : "";
174
+ if (w.outcome === "stamped") return `${w.tool || "live-import"} stamped ${w.address} into ${w.to}${at}${job}`;
175
+ if (w.outcome === "refused") return `${w.tool || "live-mv"} refused to retag ${w.address} from ${w.from} to ${w.to}${w.reason ? `: ${w.reason}` : ""}${at}${job}`;
176
+ return `${w.tool || "live-mv"} retagged ${w.address} from ${w.from} to ${w.to}${at}${job}`;
177
+ }
178
+
179
+ /** The choudoufu command a migration ran, from its record's `change`: an adoption stamps with live-import, a retag moves with live-mv. */
180
+ export function migrationTool(change) {
181
+ return change === "adopt" ? "live-import" : "live-mv";
182
+ }
183
+
184
+ /** The job number in a job's URL (Forgejo/GitHub `/actions/runs/<n>`, GitLab `/-/jobs/<n>`), or null. */
185
+ export function jobNumber(url) {
186
+ const m = typeof url === "string" ? /\/(?:actions\/runs|-\/jobs|jobs)\/(\d+)(?:[/?#]|$)/.exec(url) : null;
187
+ return m ? Number(m[1]) : null;
188
+ }
189
+
190
+ // --- slowed playback (faithfulness 1) -------------------------------------------
191
+
192
+ /** The slowed control's choices: off is real time; each other is how far apart one read's lines are drawn. */
193
+ export const SLOWED = [
194
+ { n: 1, words: "real time", stepMs: 0 },
195
+ { n: 2, words: "slowed ×2", stepMs: 25 },
196
+ { n: 4, words: "slowed ×4", stepMs: 50 },
197
+ { n: 8, words: "slowed ×8", stepMs: 100 },
198
+ ];
199
+
200
+ /** The pacing of one read's lines for a slowed factor: 0 (real time) unless a person chose to slow it. */
201
+ export function stepMsFor(n) {
202
+ const s = SLOWED.find((x) => x.n === n);
203
+ return s ? s.stepMs : 0;
204
+ }
@@ -0,0 +1,115 @@
1
+ // The tour player (behold.tour/v1): the chapter a cycle is in from its events,
2
+ // the facts filled into a chapter's lines (a fact with no record is left out),
3
+ // the live badge's lag, and a landed dot's provenance.
4
+ import { describe, it, expect } from "vitest";
5
+ import { readFileSync } from "node:fs";
6
+ import { chapterAt, firedBy, shownAt, railOf, fill, chapterLines, cardRows, lagText, LAG_WAIT_MS, provenanceText, jobNumber, stepMsFor, SLOWED, migrationTool } from "./tour-player.js";
7
+
8
+ const tour = JSON.parse(readFileSync(new URL("./tours/terralith.json", import.meta.url), "utf8"));
9
+ const beat = (b, step = "applying", at = 1_000) => ({ kind: "beat", beat: b, step, at });
10
+
11
+ describe("the chapter from demo.json's beat", () => {
12
+ it("maps each beat to its chapter, in the tour's order", () => {
13
+ const ids = ["stock", "adopt", "split", "team", "cross"].map((b) => chapterAt(tour, [beat(b)]).chapter.id);
14
+ expect(ids).toEqual(["stock", "adopt", "split", "team", "cross"]);
15
+ });
16
+
17
+ it("is the epilogue once the cross beat applied, and through the reset", () => {
18
+ expect(chapterAt(tour, [beat("cross", "applied")]).chapter.id).toBe("epilogue");
19
+ expect(chapterAt(tour, [{ kind: "beat", beat: null, step: "reset", at: 5 }]).chapter.id).toBe("epilogue");
20
+ });
21
+
22
+ it("is no chapter before any trigger fires", () => {
23
+ expect(chapterAt(tour, [])).toBeNull();
24
+ expect(chapterAt(tour, [beat("stock", "applying", 50)], 10)).toBeNull();
25
+ });
26
+
27
+ it("says how far a chapter has got from the step, and the rail marks done, current and ahead", () => {
28
+ const at = chapterAt(tour, [beat("split", "applied")], Infinity, "applied");
29
+ expect(at.progress).toBe(1);
30
+ expect(chapterAt(tour, [beat("split", "planned")], Infinity, "planned").progress).toBeCloseTo(1 / 7);
31
+ expect(railOf(tour, at).map((c) => c.state)).toEqual(["done", "done", "current", "ahead", "ahead", "ahead"]);
32
+ });
33
+ });
34
+
35
+ describe("triggers on lines and waves", () => {
36
+ it("fires on a migration's last line, and on a wave only after the named run's finish", () => {
37
+ const events = [
38
+ { kind: "line", migration: "split", line: "first", at: 10 },
39
+ { kind: "wave", wave: 1, edge: "start", at: 20 },
40
+ { kind: "wave", wave: 1, edge: "start", at: 40 },
41
+ ];
42
+ expect(firedBy({ migration: "split", line: "last" }, events)).toBeNull();
43
+ expect(firedBy({ migration: "split", line: "first" }, events).at).toBe(10);
44
+ expect(firedBy({ wave: 1, edge: "start", after_at: 30 }, events).at).toBe(40);
45
+ expect(firedBy({ wave: 1, edge: "start", blocked: true }, events)).toBeNull();
46
+ });
47
+
48
+ it("shows a visual with no `when` at once, and one with a `when` once it fires", () => {
49
+ const ch = { show: [{ kind: "light" }, { kind: "checks", when: { migration: "split", line: "last" } }] };
50
+ expect(shownAt(ch, []).map((s) => s.kind)).toEqual(["light"]);
51
+ expect(shownAt(ch, [{ kind: "line", migration: "split", line: "last", at: 7 }]).map((s) => s.kind)).toEqual(["light", "checks"]);
52
+ });
53
+ });
54
+
55
+ describe("facts in a chapter's lines", () => {
56
+ const team = tour.chapters.find((c) => c.id === "team");
57
+
58
+ it("fills the contrast from both plans' numbers", () => {
59
+ expect(chapterLines(team, { teamPlanned: 3, planned: 82, of: 82 })).toEqual(["Team B changes one policy, and only team B is planned.", "Planned 3 of 82 · chapter 1: 82 of 82"]);
60
+ });
61
+
62
+ it("leaves a line out when a fact it names has no record, never showing 0", () => {
63
+ expect(chapterLines(team, { planned: 82, of: 82 })).toEqual(["Team B changes one policy, and only team B is planned."]);
64
+ expect(fill("{n} moved", {})).toBeNull();
65
+ expect(fill("{n} refused", { n: 0 })).toBe("0 refused");
66
+ });
67
+
68
+ it("drops an epilogue row whose record is missing", () => {
69
+ const rows = cardRows([{ label: "tag writes", text: "{writes}" }, { label: "recreated", text: "{recreated}" }], { writes: 86 });
70
+ expect(rows).toEqual([{ label: "tag writes", text: "86" }]);
71
+ });
72
+ });
73
+
74
+ describe("the live badge's lag", () => {
75
+ const now = Date.parse("2026-10-17T17:00:00Z");
76
+ it("counts from the newest line's time", () => {
77
+ expect(lagText("2026-10-17T16:59:48Z", now, true)).toBe("last write 12 s ago");
78
+ expect(lagText(now - 5 * 60_000, now, false)).toBe("last write 5 min ago");
79
+ });
80
+ it("says it waits for the job once the gap passes a minute while a migration runs", () => {
81
+ expect(lagText(now - LAG_WAIT_MS - 1, now, true)).toBe("waiting for the job");
82
+ expect(lagText(now - LAG_WAIT_MS - 1, now, false)).toBe("last write 1 min ago");
83
+ });
84
+ it("says nothing with no write to count from", () => {
85
+ expect(lagText(null, now, true)).toBeNull();
86
+ });
87
+ });
88
+
89
+ describe("a landed dot's provenance", () => {
90
+ it("names the write, its time and its job", () => {
91
+ expect(provenanceText({ outcome: "moved", tool: "live-mv", address: "aws_iam_role.team_0000_role", from: "tl54-terralith", to: "tl54-team-a", at: "2026-10-17T16:57:49.66896996Z", job: 3655 })).toBe(
92
+ "live-mv retagged aws_iam_role.team_0000_role from tl54-terralith to tl54-team-a at 16:57:49.668 UTC · job #3655",
93
+ );
94
+ });
95
+ it("names a stamp and a refusal in their own words, and leaves out a job no run names", () => {
96
+ expect(provenanceText({ outcome: "stamped", tool: "live-import", address: "aws_ecs_cluster.main", to: "tl54-terralith", at: "2026-10-17T16:54:06.283Z" })).toBe("live-import stamped aws_ecs_cluster.main into tl54-terralith at 16:54:06.283 UTC");
97
+ expect(provenanceText({ outcome: "refused", address: "aws_ecs_service.a", from: "x", to: "y", reason: "marker rewrite", at: "bad" })).toBe("live-mv refused to retag aws_ecs_service.a from x to y: marker rewrite");
98
+ });
99
+ it("reads the job number from a run's URL, and the tool from the record's change", () => {
100
+ expect(jobNumber("http://forgejo:3000/a/b/actions/runs/3655")).toBe(3655);
101
+ expect(jobNumber("https://gitlab.example/a/-/jobs/12")).toBe(12);
102
+ expect(jobNumber(null)).toBeNull();
103
+ expect(migrationTool("adopt")).toBe("live-import");
104
+ expect(migrationTool("retag")).toBe("live-mv");
105
+ });
106
+ });
107
+
108
+ describe("slowed playback", () => {
109
+ it("is real time unless a person picks a slowed factor", () => {
110
+ expect(SLOWED[0]).toEqual({ n: 1, words: "real time", stepMs: 0 });
111
+ expect(stepMsFor(1)).toBe(0);
112
+ expect(stepMsFor(4)).toBe(50);
113
+ expect(SLOWED.slice(1).every((s) => s.words.startsWith("slowed ×"))).toBe(true);
114
+ });
115
+ });
@@ -0,0 +1,182 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "behold.tour/v1",
4
+ "title": "A behold tour: chapters over a cycle's real events",
5
+ "type": "object",
6
+ "required": ["schema", "name", "chapters"],
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "schema": { "const": "behold.tour/v1" },
10
+ "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$" },
11
+ "title": { "type": "string", "maxLength": 120 },
12
+ "match": {
13
+ "description": "Which demo cycles this tour narrates: demo.json's tool or scenario.",
14
+ "type": "object",
15
+ "additionalProperties": false,
16
+ "minProperties": 1,
17
+ "properties": { "tool": { "type": "string" }, "scenario": { "type": "string" } }
18
+ },
19
+ "home": {
20
+ "description": "The repo {repo} names, under demo.json's repo's owner; without it, demo.json's repo.",
21
+ "type": "string",
22
+ "pattern": "^[A-Za-z0-9._-]{1,100}$"
23
+ },
24
+ "steps": {
25
+ "description": "demo.json steps in the order a beat walks them, for how far a chapter has got.",
26
+ "type": "array",
27
+ "items": { "type": "string" },
28
+ "maxItems": 20
29
+ },
30
+ "runs": {
31
+ "description": "Named runs of the cycle, each found in the reports' index or by a migration record's commit.",
32
+ "type": "object",
33
+ "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9]{0,31}$" },
34
+ "additionalProperties": { "$ref": "#/$defs/run" }
35
+ },
36
+ "facts": {
37
+ "description": "Named numbers and values, each taken from a record. A fact with no record behind it is left out.",
38
+ "type": "object",
39
+ "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9]{0,31}$" },
40
+ "additionalProperties": { "$ref": "#/$defs/fact" }
41
+ },
42
+ "chapters": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/$defs/chapter" } }
43
+ },
44
+ "$defs": {
45
+ "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9]{0,31}$" },
46
+ "run": {
47
+ "oneOf": [
48
+ {
49
+ "type": "object",
50
+ "additionalProperties": false,
51
+ "required": ["migration"],
52
+ "properties": { "migration": { "type": "string", "pattern": "^[A-Za-z0-9._~@+-]{1,128}$" } }
53
+ },
54
+ {
55
+ "type": "object",
56
+ "additionalProperties": false,
57
+ "required": ["repo", "stage"],
58
+ "properties": {
59
+ "repo": { "type": "string", "description": "The forge repo; {repo} is demo.json's repo." },
60
+ "stage": { "enum": ["tf-plan", "tf-apply"] },
61
+ "wave": { "type": "integer", "minimum": 1 },
62
+ "pull": { "type": "null", "description": "null: a run with no pull request (a push)." },
63
+ "after": { "$ref": "#/$defs/name", "description": "Only runs that finished after this named run." },
64
+ "pick": { "enum": ["first", "last"] }
65
+ }
66
+ }
67
+ ]
68
+ },
69
+ "fact": {
70
+ "oneOf": [
71
+ {
72
+ "type": "object",
73
+ "additionalProperties": false,
74
+ "required": ["run", "value"],
75
+ "properties": {
76
+ "run": { "$ref": "#/$defs/name" },
77
+ "value": { "enum": ["planned", "changed", "recreated", "output", "job"] },
78
+ "output": { "type": "string" }
79
+ }
80
+ },
81
+ {
82
+ "type": "object",
83
+ "additionalProperties": false,
84
+ "required": ["migration", "value"],
85
+ "properties": {
86
+ "migration": { "type": "string" },
87
+ "value": { "enum": ["stamped", "moved", "refused", "skipped", "writes", "version_id", "approved_by", "moved_resources", "stamped_resources", "refused_resources"] }
88
+ }
89
+ },
90
+ {
91
+ "description": "The distinct resources a tag write landed on across these migrations' progress lines.",
92
+ "type": "object",
93
+ "additionalProperties": false,
94
+ "required": ["tagged"],
95
+ "properties": { "tagged": { "type": "array", "minItems": 1, "items": { "type": "string" } } }
96
+ },
97
+ { "type": "object", "additionalProperties": false, "required": ["sum"], "properties": { "sum": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/name" } } } },
98
+ { "type": "object", "additionalProperties": false, "required": ["approvals"], "properties": { "approvals": { "const": true } } },
99
+ {
100
+ "type": "object",
101
+ "additionalProperties": false,
102
+ "required": ["duration"],
103
+ "properties": {
104
+ "duration": {
105
+ "type": "object",
106
+ "additionalProperties": false,
107
+ "required": ["from", "to"],
108
+ "properties": { "from": { "const": "started_at" }, "to": { "$ref": "#/$defs/name" } }
109
+ }
110
+ }
111
+ }
112
+ ]
113
+ },
114
+ "trigger": {
115
+ "oneOf": [
116
+ {
117
+ "type": "object",
118
+ "additionalProperties": false,
119
+ "minProperties": 1,
120
+ "properties": { "beat": { "type": "string" }, "step": { "type": "string" } }
121
+ },
122
+ {
123
+ "type": "object",
124
+ "additionalProperties": false,
125
+ "required": ["migration", "line"],
126
+ "properties": { "migration": { "type": "string" }, "line": { "enum": ["first", "last"] } }
127
+ },
128
+ {
129
+ "type": "object",
130
+ "additionalProperties": false,
131
+ "required": ["wave", "edge"],
132
+ "properties": { "wave": { "type": "integer", "minimum": 1 }, "edge": { "enum": ["start", "end"] }, "after": { "$ref": "#/$defs/name" } }
133
+ },
134
+ {
135
+ "type": "object",
136
+ "additionalProperties": false,
137
+ "required": ["any"],
138
+ "properties": { "any": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/trigger" } } }
139
+ }
140
+ ]
141
+ },
142
+ "show": {
143
+ "description": "One visual, each standing on a record: a run's plan, a migration record, the read threads of a plan.",
144
+ "type": "object",
145
+ "additionalProperties": false,
146
+ "minProperties": 1,
147
+ "properties": {
148
+ "light": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/name" }, "description": "Light what the first of these runs planned (the first that planned anything)." },
149
+ "pulse": { "$ref": "#/$defs/name", "description": "Pulse the boxes of the roots this run planned." },
150
+ "travel": { "$ref": "#/$defs/name", "description": "This plan's output value, along its read threads to its readers." },
151
+ "output": { "type": "string" },
152
+ "wave": { "type": "integer", "minimum": 1 },
153
+ "state": { "type": "string", "description": "A migration's source state file, by its version id." },
154
+ "checks": { "$ref": "#/$defs/name", "description": "Each root of this run that plans no change." },
155
+ "counts": { "const": "estates" },
156
+ "card": {
157
+ "type": "array",
158
+ "maxItems": 8,
159
+ "items": { "type": "object", "additionalProperties": false, "required": ["label", "text"], "properties": { "label": { "type": "string" }, "text": { "type": "string" } } }
160
+ },
161
+ "when": { "$ref": "#/$defs/trigger" }
162
+ }
163
+ },
164
+ "chapter": {
165
+ "type": "object",
166
+ "additionalProperties": false,
167
+ "required": ["id", "trigger", "title"],
168
+ "properties": {
169
+ "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" },
170
+ "trigger": { "$ref": "#/$defs/trigger" },
171
+ "title": { "type": "string", "maxLength": 80 },
172
+ "text": { "type": "array", "maxItems": 2, "items": { "type": "string", "maxLength": 120 } },
173
+ "focus": {
174
+ "type": "object",
175
+ "additionalProperties": false,
176
+ "properties": { "boxes": { "enum": ["source", "all", "lit"] } }
177
+ },
178
+ "show": { "type": "array", "maxItems": 8, "items": { "$ref": "#/$defs/show" } }
179
+ }
180
+ }
181
+ }
182
+ }