yichus 0.2.0 → 0.3.1

package/dist/studio-page/studio-views.js

@@ -0,0 +1,256 @@
+// The studio page's two person diagrams, drawn from records that hold only
+// the person's words (packages/yichus-cli/src/studio/person.ts builds them):
+//
+//   mountSections(root, layers)       the app's sections as a stack, the layer
+//                                     diagram's stack (layer-diagram.js), each
+//                                     layer built only from the layers below it
+//   mountWhatHappens(root, record)    each described action's decision tree in
+//                                     the person's words, ending in the
+//                                     what-happens view's outcome caps
+//   showMarks(marks)                  the agent's notes, layered over both as
+//                                     a conversation: each bubble points at
+//                                     the part it is about
+//   reportViewing(send)               tells the studio what the person has in
+//                                     view, by id only, so the agent sees it
+//
+// The words the person's agent wrote are italic, as in what-happens.js;
+// the marks, the colours and the checks are computed. A part nobody has
+// named yet says so instead of showing its code name.
+import { el, svg } from './dom.js';
+import { stackLayout } from './layer-diagram.js';
+import { outcomeMark } from './what-happens.js';
+import { SANS, textWidth, clipText } from './label-fit.js';
+
+const NOT_NAMED = 'a part not named yet';
+const NAME = [13, 600], DOES = [11.5, 400], inset = 12;
+const NOT_NAMED_RECORD = 'a kind of record not named yet';
+// A phrase is computed text with the agent's own words ({ theirs }) in it.
+const listed = (verb, names) => [verb, ...names.flatMap((n, i) => [...i ? [', '] : [], n === null ? NOT_NAMED_RECORD : { theirs: n }])];
+const doesOf = s => {
+  const parts = [s.changes.length ? listed('changes ', s.changes) : null, s.looks.length ? listed('looks at ', s.looks) : null].filter(Boolean);
+  return parts.length ? parts.flatMap((p, i) => [...i ? [' · '] : [], ...p]) : ['keeps no records itself'];
+};
+const plain = phrase => phrase.map(p => typeof p === 'string' ? p : p.theirs).join('');
+const measure = (text, [size, weight], italic = false) => textWidth(text, size, false, weight, italic, SANS);
+const label = (text, [size, weight], room, italic = false) => clipText(text, size, room, false, weight, italic, SANS);
+const nameOf = s => s.name ?? NOT_NAMED;
+
+export function mountSections(root, layers) {
+  const draw = () => {
+    const width = Math.max(300, root.clientWidth);
+    // A tile is as wide as its words, up to the frame; longer words are
+    // shortened to fit and keep their whole text in the tile's title.
+    const widest = width - 2 * inset - 24;
+    const items = layers.map((layer, i) => layer.map((s, k) => ({ name: `section:${i}:${k}`,
+      min: Math.min(widest, Math.max(measure(nameOf(s), NAME, !!s.name), measure(plain(doesOf(s)), DOES, true)) + 2 * inset), weight: 1 + Math.sqrt(s.uses), s })));
+    const laid = stackLayout(items, width);
+    const text = (cls, x, y, words, font, room, key, italic = false) => svg('text', { class: cls, x, y, 'font-family': SANS, 'font-size': font[0], 'font-weight': font[1],
+      ...(italic ? { 'font-style': 'italic' } : {}), 'data-fit': key }, label(words, font, room, italic));
+    // A phrase is shortened as a whole, measured at its wider style, and the
+    // agent's words in what is left stay italic.
+    const phrase = (cls, x, y, words, font, room, key) => {
+      const whole = plain(words);
+      const kept = [label(whole, font, room, false), label(whole, font, room, true)].reduce((a, b) => (a.length <= b.length ? a : b));
+      const cut = kept.endsWith('…') && kept !== whole ? kept.length - 1 : whole.length;
+      let at = 0;
+      const spans = words.flatMap(p => {
+        const t = typeof p === 'string' ? p : p.theirs, piece = t.slice(0, Math.max(0, cut - at));
+        at += t.length;
+        return piece ? [svg('tspan', typeof p === 'string' ? {} : { 'font-style': 'italic' }, piece)] : [];
+      });
+      return svg('text', { class: cls, x, y, 'font-family': SANS, 'font-size': font[0], 'font-weight': font[1], 'data-fit': key },
+        spans, cut < whole.length ? svg('tspan', {}, '…') : []);
+    };
+    const picture = svg('svg', { class: 'studio-stack', viewBox: `0 0 ${laid.width} ${laid.height}`, width: laid.width, height: laid.height, role: 'img',
+      'aria-label': `Your app in ${layers.length} layers, the top first: each is built only from the layers below it`, 'data-fit': 'canvas' },
+    svg('rect', { class: 'studio-canvas', width: laid.width, height: laid.height, 'data-box': 'canvas' }),
+    laid.bands.map((b, i) => svg('rect', { class: 'studio-band', 'data-shade': i % 2, x: 0, y: b.top, width: laid.width, height: b.height })),
+    laid.tiles.map(({ item: { name: key, s }, x, y, w, h }) => svg('g', { class: 'studio-section', 'data-named': String(!!s.name), 'data-anchor': s.anchor },
+      svg('title', {}, `${nameOf(s)}: ${plain(doesOf(s))}`),
+      svg('rect', { x, y, width: w, height: h, rx: 6, 'data-box': key }),
+      text('studio-section-name', x + inset, y + h / 2 - 4, nameOf(s), NAME, w - 2 * inset, key, !!s.name),
+      phrase('studio-section-does', x + inset, y + h / 2 + 13, doesOf(s), DOES, w - 2 * inset, key))));
+    root.replaceChildren(picture);
+  };
+  draw();
+  // One observer per root, drawing the latest record when the frame resizes.
+  watching.get(root)?.disconnect();
+  if ('ResizeObserver' in window) {
+    let seen = root.clientWidth;
+    const observer = new ResizeObserver(() => { if (root.clientWidth !== seen) { seen = root.clientWidth; draw(); } });
+    observer.observe(root);
+    watching.set(root, observer);
+  }
+}
+const watching = new WeakMap();
+
+const TICK = { holds: '✓', fails: '✗', 'cannot say': '?' };
+function cap(outcome) {
+  const mark = svg('svg', { class: 'studio-cap', viewBox: '0 0 20 20', width: 20, height: 20, 'aria-hidden': 'true' });
+  // outcomeMark draws from a status and a flag only, never from text
+  mark.innerHTML = outcomeMark(10, 10, outcome.status, outcome.refused);
+  return mark;
+}
+const words = (text, missing) => text ? el('em', {}, text) : el('span', { class: 'studio-unnamed' }, missing);
+const outcomes = s => (s.kind === 'outcome' ? 1 : s.ways.reduce((n, w) => n + outcomes(w.then), 0));
+const way = w => el('p', { class: 'studio-way', 'data-anchor': w.then.anchor === w.anchor ? null : w.anchor }, words(w.words, 'a way not described yet'));
+// The what-happens view's spine: the way that leads on to the most outcomes
+// continues straight down; a way that ends at once is a stub beside it; any
+// other way that leads on is folded behind its words, like the view's bundle.
+function step(s) {
+  if (s.kind === 'outcome') return el('div', { class: 'studio-outcome', 'data-status': s.status, 'data-anchor': s.anchor },
+    cap(s), el('span', { class: 'studio-said' }, el('span', { class: 'studio-end' }, s.refused ? 'turned away' : 'answered'), s.words ? [' ', el('em', {}, s.words)] : []),
+    s.checks.length ? el('ul', { class: 'studio-checks' }, s.checks.map(c => el('li', { 'data-verdict': c.verdict },
+      `${TICK[c.verdict]} `, c.says.map(p => typeof p === 'string' ? p : el('em', {}, p.theirs))))) : []);
+  const on = s.ways.filter(w => w.then.kind === 'choice').sort((a, b) => outcomes(b.then) - outcomes(a.then));
+  const [main, ...folded] = on;
+  return [
+    el('p', { class: 'studio-ask', 'data-anchor': s.anchor }, words(s.words, 'a check not described yet')),
+    el('ul', { class: 'studio-ways' },
+      s.ways.filter(w => w.then.kind === 'outcome').map(w => el('li', {}, way(w), step(w.then))),
+      folded.map(w => el('li', {}, el('details', { class: 'studio-fold' },
+        el('summary', { 'data-anchor': w.anchor }, words(w.words, 'a way not described yet'), ` · ${outcomes(w.then)} ways it can end`), el('div', { class: 'studio-folded' }, step(w.then)))))),
+    main ? [el('p', { class: 'studio-on', 'data-anchor': main.anchor }, '↓ ', words(main.words, 'a way not described yet')), step(main.then)] : [],
+  ];
+}
+
+export function mountWhatHappens(root, record) {
+  root.replaceChildren(
+    ...record.actions.map(a => el('section', { class: 'studio-action' },
+      el('h3', { 'data-anchor': a.anchor }, words(a.title, 'an action not described yet')),
+      a.first ? el('div', { class: 'studio-tree' }, step(a.first)) : el('p', { class: 'empty' }, 'This action could not be followed.'))),
+    record.waiting ? el('p', { class: 'studio-waiting' }, `${record.waiting} more ${record.waiting === 1 ? 'action is' : 'actions are'} not described yet.`) : []);
+  if (!record.actions.length && !record.waiting) root.replaceChildren(el('p', { class: 'empty' }, 'Your app has no actions yet.'));
+}
+
+// ------------------------------------------------------------ the agent
+
+// The agent's notes sit in a layer of their own above the page, like the
+// agent speaking over the pictures: each note is a bubble beside the part
+// it is about, and that part glows under it. The layer only reads where
+// the parts are drawn; it never changes a picture. A new set of notes
+// arrives one bubble at a time and the page brings the first into view.
+let layer = null, said = null, shown = [];
+const GAP = 12, EDGE = 16;
+const within = (value, low, high) => Math.max(low, Math.min(high, value));
+
+export function showMarks(marks) {
+  if (!layer) {
+    layer = document.body.appendChild(el('div', { class: 'agent-layer', role: 'log', 'aria-label': 'Notes from your agent' }));
+    // The page reflows when it is resized, a fold opens or a picture is
+    // redrawn; the notes follow their parts.
+    new ResizeObserver(() => follow()).observe(document.body);
+  }
+  const fresh = !!marks && marks.said !== said;
+  said = marks?.said ?? null;
+  if (fresh || !marks) {
+    shown = (marks?.marks ?? []).map((mark, i) => note(mark, fresh ? i : null));
+    layer.replaceChildren(...shown.flatMap(n => [n.ring, n.bubble]));
+  }
+  // New notes about steps behind a fold open the fold; once open, the fold
+  // is the person's to close, and a note about a step folded away waits.
+  if (fresh) for (const n of shown) {
+    for (let fold = n.target()?.parentElement?.closest('details'); fold; fold = fold.parentElement?.closest('details')) fold.open = true;
+  }
+  follow();
+  const first = shown.map(n => n.target()).find(Boolean);
+  if (fresh && first) first.scrollIntoView({ behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth', block: 'center' });
+}
+
+// One note: its ring, its bubble, and the part it points at, found again
+// each time, since a picture redraws its parts.
+function note(mark, order) {
+  const target = () => document.querySelector(`[data-anchor="${CSS.escape(mark.anchor)}"]`);
+  const ring = el('div', { class: 'agent-ring' });
+  const tail = el('span', { class: 'agent-tail' });
+  const close = el('button', { type: 'button', class: 'agent-close', 'aria-label': 'Hide this note' }, '×');
+  const bubble = el('div', { class: 'agent-bubble' }, tail,
+    el('p', { class: 'agent-who' }, 'Your agent', el('span', {}, ' · not checked')),
+    el('p', { class: 'agent-says' }, el('em', {}, mark.note)), close);
+  const n = { ring, bubble, tail, target };
+  close.addEventListener('click', () => { ring.remove(); bubble.remove(); shown = shown.filter(m => m !== n); follow(); });
+  if (order !== null) for (const part of [ring, bubble]) { part.classList.add('agent-in'); part.style.animationDelay = `${order * 350}ms`; }
+  return n;
+}
+
+function follow() {
+  // A part not on the page, or folded away, has its note wait.
+  const placed = shown.map(n => { const part = n.target(); return { n, part: part?.checkVisibility() ? part : null }; });
+  for (const { n, part } of placed) n.ring.hidden = n.bubble.hidden = !part;
+  // Placed down the page, so a bubble only ever waits below one above it.
+  const measured = placed.filter(p => p.part).map(({ n, part }) => ({ n, box: drawn(part) })).sort((a, b) => a.box.top - b.box.top);
+  const page = document.querySelector('main')?.getBoundingClientRect() ?? { right: innerWidth };
+  let below = -Infinity;
+  for (const { n, box } of measured) {
+    const x = box.left + scrollX, y = box.top + scrollY;
+    Object.assign(n.ring.style, { left: `${x - 4}px`, top: `${y - 4}px`, width: `${box.width + 8}px`, height: `${box.height + 8}px` });
+    const width = Math.min(300, innerWidth - 2 * EDGE);
+    // Beside the part when the page has room, so the picture stays in
+    // view; otherwise just under it.
+    const beside = box.right + GAP + width <= Math.min(page.right, innerWidth - EDGE);
+    n.bubble.dataset.side = beside ? 'right' : 'below';
+    const left = beside ? box.right + scrollX + GAP : within(x + 16, scrollX + EDGE, scrollX + innerWidth - width - EDGE);
+    const top = Math.max(beside ? y + box.height / 2 - 18 : y + box.height + GAP, below + 8);
+    Object.assign(n.bubble.style, { left: `${left}px`, top: `${top}px`, width: `${width}px` });
+    Object.assign(n.tail.style, beside ? { left: '-7px', top: `${within(y + box.height / 2 - top - 6, 10, 40)}px` }
+      : { left: `${within(x + box.width / 2 - left - 7, 12, width - 26)}px`, top: '' });
+    below = top + n.bubble.offsetHeight;
+  }
+}
+
+// Where a part's words are drawn: a picture's part as it is, a line of
+// text as far as its words reach rather than the width of its column.
+function drawn(part) {
+  if (part instanceof SVGElement) return part.getBoundingClientRect();
+  const words = document.createRange();
+  words.selectNodeContents(part);
+  return words.getBoundingClientRect();
+}
+
+// ------------------------------------------------------------ what is in view
+
+// What the person has in view, so the agent can follow along when they say
+// "this one": the page's sections and the drawn parts on screen, the
+// questions and properties shown, the folds open and the last thing they
+// clicked. Only ids go out, never words; the studio says the words from the
+// records it drew. Each report names the drawing its anchors belong to.
+// Returns the function to call after each refresh with the drawing now shown;
+// a new drawing forgets the last click, whose anchor may now be another part.
+export function reportViewing(send) {
+  let touched = null, drawing = null, sent = '', timer = 0;
+  const onScreen = node => {
+    if (!node.checkVisibility()) return false;
+    const box = node.getBoundingClientRect();
+    return box.bottom > 0 && box.top < innerHeight && box.right > 0 && box.left < innerWidth;
+  };
+  const ids = (selector, key) => [...new Set([...document.querySelectorAll(selector)].filter(onScreen).map(n => n.dataset[key]))];
+  const report = () => {
+    const now = JSON.stringify({
+      shown: document.visibilityState === 'visible',
+      sections: ids('main > section[data-section]', 'section'),
+      parts: ids('[data-anchor]', 'anchor'),
+      questions: ids('[data-question]', 'question'),
+      properties: ids('[data-property]', 'property'),
+      open: [...document.querySelectorAll('details.studio-fold[open] > summary[data-anchor]')].map(s => s.dataset.anchor),
+      touched,
+      drawing,
+    });
+    if (now !== sent) { sent = now; send(now); }
+  };
+  const soon = () => { clearTimeout(timer); timer = setTimeout(report, 500); };
+  const touch = event => {
+    const at = event.target instanceof Element ? event.target.closest('[data-anchor], [data-question], [data-property], main > section[data-section]') : null;
+    if (at) touched = at.dataset.anchor ? { kind: 'part', id: at.dataset.anchor } : at.dataset.question ? { kind: 'question', id: at.dataset.question }
+      : at.dataset.property ? { kind: 'property', id: at.dataset.property } : { kind: 'section', id: at.dataset.section };
+    soon();
+  };
+  for (const type of ['scroll', 'resize']) addEventListener(type, soon, { passive: true });
+  document.addEventListener('visibilitychange', soon);
+  document.addEventListener('toggle', soon, true);
+  document.addEventListener('click', touch, true);
+  document.addEventListener('focusin', touch);
+  return shown => {
+    if (shown !== drawing) { drawing = shown ?? null; touched = null; }
+    soon();
+  };
+}

package/dist/studio-page/system-map-record.js

@@ -1,4 +1,4 @@
-// The system map's record (schema system-map-2, marks yichus-marks-2), built
+// The system map's record (schema system-map-2, marks yichus-marks-3), built
 // from the engine's own output. web/system-map.js draws this record and
 // nothing else; every field names the engine field it was copied or derived
 // from (`from`). scripts/diagram-examples.mjs records one per program.
@@ -6,12 +6,13 @@
 // The record joins four engine calls by full id:
 //   api_report                      headline.class, surface.routes
 //   api_organize lens=structure     entries, supply, ioKinds, ports, applied,
-//                                   chains, keyed, generic, combinations, phases
+//                                   chains, keyed, generic, combinations, phases,
+//                                   programs
 //   api_organize lens=abstractions  generators, instantiations, routeShapes
 //   api_organize lens=layers        packages and their exported definitions
 // A name is copied as a label and never decides anything.
 
-export const MARKS_VERSION = 'yichus-marks-2';
+export const MARKS_VERSION = 'yichus-marks-3';
 
 // Each mark, where it sits, and the record field that draws it. It travels
 // with every record so the file describes itself.
@@ -21,10 +22,11 @@ export const VOCABULARY = {
     callers: 'left of the wall: one glyph per transport kind, HTTP above, importer below, each with a bracket over the openings it calls; the kind the program lacks is the same glyph struck through  <- callers[], ghostCallers[]',
     openings: 'the left wall: one opening per entry  <- entries[]',
     hullBand: 'the middle band of the wall: wrappers sit here and nowhere else; empty band = no entry goes through a shared wrapper  <- wrappers[]',
-    afterBand: 'between the hull band and the reply bars: work an entry does after its wrapper returns, with its stations and checks; empty = none  <- entries[].beside',
+    afterBand: 'between a hull\'s right wall and the reply bars: work an entry does after its wrapper returns, with its stations and checks; empty = none  <- entries[].beside',
     replyBars: 'one bar per entry at the same x, past the hull band  <- entries[]',
     rail: 'the bottom of the wall: a handle handed in from outside, with a riser to each use; a ? on the rail where a use is handed in on some paths only  <- uses[how=handed|mixed]',
     rack: 'right of the wall: db, model, net, always in this order; struck = the engine checked and found none  <- resources[], ghostResources[]',
+    programBand: 'the bottom of the wall, under the rail: one container per pure program, its request openings on its right edge, the engine lanes right of it; empty = the engine found no program  <- programs[]',
     quietLine: 'bottom inside the wall: parts on no entry path, one stretch per package, with their forks, sockets, generic letters and steps  <- keyed[], library.applied[], steps[]',
   },
   marks: {
@@ -33,23 +35,37 @@ export const VOCABULARY = {
     role: 'red word beside the lock: a role beyond sign-in  <- entries[].roles',
     limit: 'gauge beside the path: a declared rate limit  <- entries[].limits',
     station: 'ring on a path: code touching a table, with the verb and table beside it; filled = writes  <- entries[].reach, wrappers[].effects, entries[].beside.effects',
-    modelRing: 'violet ring: the entry reaches the model; the count under the model says how many entries do  <- entries[].model',
+    modelRing: 'violet ring: the entry reaches the model  <- entries[].model',
+    reachedBy: 'under each resource in the rack: how many routes reach it, the resource drawn at that share of the routes (never smaller than its name)  <- entries[].db, model, net, beside.resources',
     netRing: 'orange ring: the entry reaches the network  <- entries[].net',
     guard: 'red diamond on the path where the check happens, its name above, failure stem below  <- entries[].guards, wrappers[].guards, entries[].passed[].guards, entries[].beside.guards',
-    hull: 'translucent region in the hull band: paths merge into it, run one shared stretch, and split; everything inside it runs inside the wrapper  <- wrappers[]',
+    hull: 'translucent region in the hull band: paths merge into it, run one shared stretch, and split; everything inside it runs inside the wrapper; its right wall, drawn in the hull ink, is where the wrapper returns  <- wrappers[]',
     socket: 'broken-rim ring: a function the caller hands in runs here; its centre fills like a station  <- entries[].passed[]',
     token: 'small grey word under a path: the value the caller fixes for the wrapper  <- entries[].policy',
     afterDot: 'dot in the after band: a call the entry makes after its wrapper returns  <- entries[].beside.calls',
     builder: 'plus-disc under a station with the call that builds the handle there  <- uses[how=local].builtBy',
-    unknown: 'a ? in a circle on the rail: the engine traced the handle only on some paths  <- uses[how=mixed]',
+    unknown: 'a ? in a circle on the rail, with "partly traced" beside it and a sentence on hover: the engine traced the handle only on some paths  <- uses[how=mixed]',
     fork: 'three prongs and a type: a choice keyed on a plain String or Int; under the mark that makes it, else on the quiet line  <- keyed[]',
-    bundle: 'one cable with a count: entries with the same wrapper and identical marks; its title names every route; opening it draws each one  <- bundles[]',
+    bundle: 'one cable with how many routes it carries ("4 routes"): entries with the same wrapper and identical marks; its title names every route; opening it draws each one  <- bundles[]',
     anchor: 'where the rail starts: platform when no definition of the program can make the handle; ? when the trace stops and the program could  <- uses[].anchor',
-    step: 'loop arc with a type on the quiet line: functions of the package take that type and return it  <- steps[]',
+    step: 'loop arc with a type on the quiet line: functions of the package take that type and return it; gathered, a count in words ("8 steps"), as are choices, db uses and generic parts  <- steps[]',
     loop: 'loop arc with package names: packages whose types lead back to themselves  <- phases.cycles',
     composes: 'hull round a chain: a definition takes the type the chain hands in at each step and applies it  <- library.applied[].fedBy',
     port: 'plug strip on the right: a record of functions; each adapter a plug, hollow when nothing plugs it in  <- library.ports[]',
     generic: 'the letter ∀ with its variables over a part that never looks inside what it carries  <- library.generic[]',
+    program: 'large container: a pure program, its step and package named, with its package\'s own definition count (as the layer stack counts them) and how many more it uses from other packages, the most used named with their counts; routes that act on one step\'s answer per call are named as its starters ("one step per call of"), and routes that only replay it are named on hover  <- programs[], definitions, usesElsewhere, elsewhere[], starters[advances=false], replays[]',
+    decision: 'bar and number in the program: its decisions, on one scale shared with its engines\' bars  <- programs[].decisions',
+    struck: 'on a program, a struck "effects": no definition in its package performs an effect  <- programs[].beside = []',
+    programEffect: 'red disc and count on a program: definitions in its own package that perform effects, named in its title  <- programs[].beside[]',
+    request: 'opening on the program\'s right edge: a request constructor its step can return, with its payload\'s types  <- programs[].requests[]',
+    variant: 'short opening under a request: a constructor of a user sum type its payload carries, with what the program calls it ("BriefCase → Lawyer") where a total match maps each kind to a plain constructor; eight drawn, the rest counted with their names in a title  <- programs[].requests[].variants[], namings[]',
+    starter: 'dashed line from a route\'s reply bar into the program top: the route calls the step with its values and acts on the answer, found by value flow; a route that runs an engine is named under its loop instead  <- programs[].starters[advances=false]',
+    gap: 'struck opening: a request constructor no engine handles  <- programs[].gaps[]',
+    wire: 'line from an opening to the lane that handles it, ending in the names of the resources the arm reaches, or a dot each where they do not fit  <- programs[].requests[].handledBy',
+    lane: 'thin vertical line on the resource side: an engine that performs the program\'s requests, its package above it (package.definition where lanes share one) and what it does written from its type (its own parameters → what its effect yields), its code name and whole type on hover; it ends in the resources its arms reach, then dashed pills under "also" for resources it reaches for no request  <- programs[].engines[], pkgLabel, type, resources, also',
+    laneFork: 'bar and number on a lane: the engine\'s decisions, on the program\'s scale; 0 = a rule-free engine  <- programs[].engines[].decisions',
+    replyLoop: 'one solid arc from a lane\'s foot back into the program, with one loop node naming what repeats the step within one call, and "each call of … runs it" naming the routes that run the rounds  <- programs[].engines[].replies, loop, starters',
+    replaced: 'a check named "(in place of …)": in the compared base record the same route had that other check at the same place, and it is on that route no longer; says nothing about whether the two do the same  <- compare.replaced[]',
   },
   rule: 'every guard, wrapper, socket, fork, handle, station, step and resource the engine records is drawn at its fixed place, in every view; where nothing is drawn, the engine checked and found none.',
 };
@@ -66,6 +82,75 @@ export function effectsOf(steps) {
 }
 const isWrite = op => op !== 'read';
 const uniqBy = (xs, key) => { const seen = new Set(); return xs.filter(x => !seen.has(key(x)) && seen.add(key(x))); };
+// The resource an engine effect reaches; the program runner's two kinds by name of kind.
+const RUNNER = { CompileProgram: 'compile', RunProgram: 'run' };
+export const effectResource = e => e.resource || RUNNER[e.kind] || 'io';
+const LANE_RES = ['db', 'model', 'net', 'compile', 'run', 'io'];
+const resOrder = rs => LANE_RES.filter(r => rs.includes(r));
+
+// Programs: a pure step whose result carries a request, the engines that
+// perform each request, and the requests no engine handles.
+export function programsOf(st, layers = null) {
+  const found = (st.programs && st.programs.programs) || [];
+  // a package's own definitions, counted as the layers lens counts them
+  const ownCount = pkg => { const lp = layers && layers.packages.find(x => x.name === pkg); return lp ? lp.definitions.length : null; };
+  return found.map(p => {
+    const engines = p.engines.map(e => {
+      const resources = resOrder(uniq(e.handles.flatMap(h => h.effects.map(effectResource))));
+      return {
+      id: e.id, label: bare(e.id), pkg: pkgOf(e.id), pkgLabel: pkgOf(e.id).split('/').pop(),
+      handles: e.handles.map(h => h.constructor),
+      resources,
+      // effects the engine performs that are no request's: drawn, not hidden
+      also: resOrder(uniq((e.effects || []).map(effectResource))).filter(r => !resources.includes(r)),
+      replies: resOrder(uniq(e.replies.map(effectResource))),
+      decisions: +e.decisions, entries: e.entries, truncated: e.truncated,
+      loop: e.loop ? { kind: e.loop.kind, by: e.loop.by, label: e.loop.by ? bare(e.loop.by) : null } : { kind: 'sequence', by: null, label: null },
+      starters: (p.starters || []).filter(s => s.advances && s.via.some(v => v === e.id || e.entries.includes(s.entry))).map(s => s.entry),
+      // what it does, from its type: the program's own and standard parameters, and what its effect yields; the whole type on hover
+      type: { takes: e.labels.takes, returns: e.labels.returns, plainTakes: e.labels.plainTakes, yields: e.labels.yields,
+        from: 'structure.programs.programs[].engines[].labels' },
+      from: 'structure.programs.programs[].engines[]',
+    }; });
+    const requests = p.requests.map(q => ({
+      constructor: q.constructor, fields: q.fields.map(f => f.label),
+      variants: (q.variants || []).map(v => ({ path: v.path, type: bare(v.type), constructors: v.constructors,
+        // what the program calls each kind: total matches onto plain constructors, the type's own package first
+        namings: (v.namings || []).slice().sort((a, b) => (pkgOf(b.definition) === pkgOf(v.type)) - (pkgOf(a.definition) === pkgOf(v.type))).map(n => ({
+          definition: n.definition, label: bare(n.definition), type: bare(n.type), names: n.names.map(x => ({ constructor: x.constructor, name: x.name })),
+          from: 'structure.programs.programs[].requests[].variants[].namings[]' })),
+        from: 'structure.programs.programs[].requests[].variants[]' })),
+      handledBy: p.engines.filter(e => e.handles.some(h => h.constructor === q.constructor)).map(e => ({
+        engine: e.id, resources: resOrder(uniq(e.handles.find(h => h.constructor === q.constructor).effects.map(effectResource))) })),
+      gap: p.gaps.some(g => g.constructor === q.constructor),
+      from: 'structure.programs.programs[].requests[] + engines[].handles[]',
+    }));
+    return {
+      id: p.step, label: bare(p.step), pkg: p.package, pkgLabel: p.package.split('/').pop(),
+      result: bare(p.result), requestType: bare(p.requestType), carrier: p.carrier,
+      decisions: +p.decisions, finishes: p.finishes,
+      // definitions: the package's own, as the layer stack counts them; reached: everything the program's definitions use
+      definitions: ownCount(p.package) ?? +(p.ownDefinitions || 0), reached: p.definitions.length,
+      // of what it reaches, the definitions that live in other packages
+      usesElsewhere: p.definitions.filter(d => pkgOf(d) !== p.package).length,
+      // and which packages those are, the most used first
+      elsewhere: Object.entries(p.definitions.filter(d => pkgOf(d) !== p.package).reduce((m, d) => ({ ...m, [pkgOf(d)]: (m[pkgOf(d)] || 0) + 1 }), {}))
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([pkg, n]) => ({ pkg, label: pkg.split('/').pop(), n, from: 'structure.programs.programs[].definitions[]' })),
+      requests, engines,
+      starters: (p.starters || []).map(s => ({ entry: s.entry, path: s.entry.replace(/^route:/, ''), advances: s.advances, via: s.via,
+        from: 'structure.programs.programs[].starters[]' })),
+      // routes that call the step and act on nothing it says: they read where the program is
+      replays: (p.replays || []).map(s => ({ entry: s.entry, path: s.entry.replace(/^route:/, ''), via: s.via, from: 'structure.programs.programs[].replays[]' })),
+      // what each reaches, as the structure lens's effect sites say (io when none is a resource)
+      beside: (p.beside || []).map(b => ({ id: b.definition, label: bare(b.definition), kinds: b.kinds,
+        resources: resOrder(uniq((st.ioKinds || []).filter(k => k.definition === b.definition).flatMap(k => k.resources))),
+        from: 'structure.programs.programs[].beside[], structure.ioKinds[].resources' })),
+      gaps: p.gaps.map(g => ({ constructor: g.constructor, from: 'structure.programs.programs[].gaps[]' })),
+      from: 'structure.programs.programs[]',
+    };
+  });
+}
+
 const outsideResourcesOf = steps => uniq((steps || []).map(e => e.resource).filter(r => r === 'model' || r === 'net'));
 
 export function buildSystemMap(engine, { program }) {
@@ -106,7 +191,7 @@ export function buildSystemMap(engine, { program }) {
       roles: r.requiredRoles || [],
       limits, limitComputed: ee.limits.written === 'computed',
       reachKinds: ee.reaches,
-      model: ee.resources.includes('model'), net: ee.resources.includes('net'),
+      db: ee.resources.includes('db'), model: ee.resources.includes('model'), net: ee.resources.includes('net'),
       writes: reach.some(e => isWrite(e.op)),
       guards: rs.handlerGuards.map(bare), guardIds: rs.handlerGuards,
       wrapper, via: rs.viaSpecialization ? bare(rs.viaSpecialization) : null,
@@ -209,6 +294,7 @@ export function buildSystemMap(engine, { program }) {
     kind: routes.length ? 'service' : 'library',
     callers, ghostCallers, entries, wrappers, parts, uses, resources, ghostResources,
     library, keyed, steps,
+    programs: programsOf(st, layers),
     bundles: routes.length > 12 ? bundlesOf(entries, uses, keyed) : null,
     phases: st.phases,
     evidence: { tools: ['api_report', 'api_organize:abstractions', 'api_organize:structure', 'api_organize:layers'], headline: report.headline,
@@ -216,6 +302,34 @@ export function buildSystemMap(engine, { program }) {
   };
 }
 
+// Two versions of one program: a check whose place on a route's path (the
+// handler's own checks, the handed-in function's, the after band's, by
+// position) holds a different definition in the head than in the base,
+// where neither definition is anywhere else on that route, took the old
+// one's place. That is all it says: nothing here shows the two do the
+// same. A route only in one version is left alone.
+export function replacedGuards(base, head) {
+  const slots = e => [['handler', e.guardIds], ['passed', e.passed[0]?.guardIds || []], ['after', e.beside?.guardIds || []]];
+  const byPath = new Map(base.entries.map(e => [e.path, e]));
+  const out = [];
+  for (const e of head.entries) {
+    const b = byPath.get(e.path);
+    if (!b) continue;
+    const all = x => new Set(slots(x).flatMap(([, ids]) => ids));
+    const ba = all(b), ha = all(e);
+    for (const [[slot, hs], [, bs]] of slots(e).map((s, i) => [s, slots(b)[i]]))
+      hs.forEach((id, i) => {
+        const was = bs[i];
+        if (was && was !== id && !ha.has(was) && !ba.has(id)) {
+          // the label tells the two apart: the old one's package too when both have one name
+          const wasLabel = bare(was) === bare(id) ? `${pkgOf(was).split('/').pop()}::${bare(was)}` : bare(was);
+          out.push({ entry: e.key, within: slot, at: i, guard: id, was, wasLabel, from: 'derived: the same place on the same route in the base record' });
+        }
+      });
+  }
+  return out;
+}
+
 export const keyKindOf = e => e.authority === 'publishable' ? 'publishable' : e.signedIn ? 'secret' : 'public';
 
 // Bundles: entries that share a wrapper and draw identical marks. Names,