yichus 0.3.2 → 0.3.3

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

@@ -38,15 +38,16 @@ export const VOCABULARY = {
     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',
+    guard: 'red diamond on the path where the route can refuse, the check named above it (the program\u2019s definition it calls, "<table> row found", "<table> row\u2019s <field>" for a branch on a field of a read row, or "a test in <definition>" for a comparison or library answer that definition branches on), failure stem below; a branch no path refuses on is not drawn here  <- entries[].guards (structure.scenarios[]: branches where one arm ends only in refusals), wrappers[].guards, entries[].passed[].guards, entries[].beside.guards',
+    policy: 'under the db, each table with its access policy as the access check proves it: own = each caller reads and writes only their own row; no row rule = the access check holds no rule over its rows, so who reads or writes which row is decided only by the code drawn on the routes; guarded = rows pass the named guard; role … only = only callers with that role reach its rows; unchecked = the access check gave this table no verdict; a policy ending \u201cbroken\u201d is one the code breaks, and \u201cnot proven\u201d one the check could not settle; counted when the tables are too many to list  <- resources[kind=db].policies',
     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, 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 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[]',
+    fork: 'three prongs and a type: a choice keyed on a plain String or Int; under the mark that makes it (under a list of checks, named by the check it is inside: "can_see on String"), else on the quiet line  <- keyed[]',
+    bundle: 'one cable with how many routes it carries ("4 routes"): entries with the same wrapper and identical marks; its title names every route: by the one part of the path that differs, among at most six ("/{tags, tasks}/sync"), or each by name when there are at most four; else a pattern with *; 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; 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',
@@ -67,6 +68,7 @@ export const VOCABULARY = {
     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[]',
   },
+  names: 'every check, call and table name is a label the code\'s author (often an AI) chose; the picture proves where a check runs, what it is given and what happens when it fails, never what it decides: a reader who doubts the author reads that rule itself.',
   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.',
 };
 
@@ -153,9 +155,67 @@ export function programsOf(st, layers = null) {
 
 const outsideResourcesOf = steps => uniq((steps || []).map(e => e.resource).filter(r => r === 'model' || r === 'net'));
 
+// The branches of an entry's what-happens tree where a path can refuse:
+// one arm ends only in refusals and another does not (structure.scenarios[],
+// present when the structure lens is asked with requirements). The
+// platform's own sign-in or role check is the lock's, and its transaction's
+// busy or unconfirmed answers are the transaction's, not a branch here.
+const leavesUnder = t => (t.kind === 'leaf' ? [t] : t.arms.flatMap(a => leavesUnder(a.next)));
+function refusingForks(tree) {
+  const out = [];
+  const go = t => {
+    if (!t || t.kind !== 'node') return;
+    const refused = t.arms.map(a => leavesUnder(a.next).every(l => l.outcome.kind === 'refused'));
+    if (t.concern?.layer !== 'platform' && refused.some(Boolean) && !refused.every(Boolean)) out.push(t);
+    t.arms.forEach(a => go(a.next));
+  };
+  go(tree);
+  return out;
+}
+// a refusing branch by what it tests: the program's definition it calls, or the read whose row it needs;
+// a branch on a library's answer (a comparison, a platform helper) is a test the calling definition
+// writes, so it is named by that definition, the rule a reader would open
+const forkId = (n, own) => (n.from.kind === 'call' && own.has(n.from.callee) ? n.from.callee : n.id);
+// what a check's label is made of, so each code name in it can be named: the definition it names, or the table and field it reads
+const forkParts = (n, own) => (n.from.kind === 'call' && own.has(n.from.callee) ? { definition: n.from.callee }
+  : n.from.kind === 'read' && n.from.table ? { table: n.from.table, ...(n.from.path?.length ? { field: n.from.path.join('.') } : {}) }
+  : n.from.site ? { definition: n.from.site } : {});
+// the same check met on several paths: a definition by its id, any other test by what it asks where
+const forkKey = own => n => (n.from.kind === 'call' && own.has(n.from.callee) ? n.from.callee : `${forkLabel(n, own)} ${n.from.site}`);
+// a branch on a read row itself asks whether it was found; on a field of it, what that field holds
+const forkLabel = (n, own) => (n.from.kind === 'call' ? (own.has(n.from.callee) ? bare(n.from.callee) : `a test in ${bare(n.from.site)}`)
+  : n.from.kind === 'read' && n.from.table ? (n.from.path?.length ? `${n.from.table} row\u2019s ${n.from.path.join('.')}` : `${n.from.table} row found`) : n.from.site ? `a test in ${bare(n.from.site)}` : 'a computed branch');
+// a table's access policy as the access check states it (report.resources[].policy),
+// and whether the check proved the code keeps it: a rule the code breaks says so, and
+// one it could not settle (or no route reaches) is not proven
+// a table the access check gave no verdict is 'unchecked', as the key says
+const policyWord = r => {
+  const rule = policyRule(r);
+  if (rule === 'unchecked') return rule;
+  return r.status === 'violated' ? `${rule}, broken` : r.proven ? rule : `${rule}, not proven`;
+};
+const policyRule = r => {
+  const roles = () => r.roles.join(', '), guards = () => r.guards.join(', ');
+  switch (r.policyKind) {
+    case 'OwnerScoped': return 'own';
+    case 'Public': return 'no row rule';
+    case 'Guarded': return `guarded by ${guards()}`;
+    // with no guard, only the roles reach its rows
+    case 'GuardedOrRoles': return r.guards.length ? `guarded by ${guards()} or role ${roles()}` : `role ${roles()} only`;
+    case 'PublicReadRoleWrite': return `anyone reads; role ${roles()} writes`;
+    default: return 'unchecked';
+  }
+};
+
 export function buildSystemMap(engine, { program }) {
   for (const [k, v] of Object.entries(engine)) if (!v.ok) throw new Error(`${k}: ${v.error}`);
   const report = engine.report, st = engine.structure, abs = engine.abstractions.abstractions, layers = engine.layers.layers;
+  // a tree the engine stopped before finishing (truncated, or a construct it does not follow) says nothing
+  // about where its entry refuses; such an entry keeps the checks its definitions hold
+  const whole = s => s.tree && !s.truncated && !s.unsupported;
+  const trees = new Map((st.scenarios || []).filter(whole).map(s => [s.entry, refusingForks(s.tree)]));
+  // the program's own definitions, as the layers lens lists them; anything else a fork calls is a library's
+  const ownDefs = new Set(layers.packages.flatMap(p => p.definitions.map(d => `${p.name}::${d.name}`)));
   const routes = (report.surface.routes || []).slice().sort((a, b) => a.path.localeCompare(b.path));
   const engEntry = new Map(st.entries.map(e => [e.entry, e]));
   const shapes = new Map(abs.routeShapes.map(r => [r.path, r]));
@@ -164,11 +224,22 @@ export function buildSystemMap(engine, { program }) {
   const besideOf = inst => ({ calls: inst.besideCalls.map(bare), callIds: inst.besideCalls, guards: inst.besideGuards.map(bare), guardIds: inst.besideGuards,
     effects: effectsOf(inst.besideEffectSteps), resources: outsideResourcesOf(inst.besideEffectSteps), from: 'abstractions.instantiations[].beside*' });
 
+  // a generator wraps a route only when, by its type, it can: it runs effects, or IO is in its signature, or it
+  // checks or dispatches and returns whatever its caller's code returns (a type variable, or the type a function
+  // handed to it returns); a pure helper that returns a List or an Int shapes values, and cannot refuse or wrap the route
+  const resultOf = sig => (sig.includes('->') ? sig.slice(sig.lastIndexOf('->') + 2).trim() : null);
+  const returnsCallers = g => {
+    const result = resultOf(g.signature);
+    return result !== null && (/^[a-z]\w*$/.test(result)
+      || (g.parameterGroups || []).flat().some(sl => sl.role === 'function' && sl.returnType === result));
+  };
+  const wraps = g => !!g && (/\bIO\[/.test(g.signature) || g.envelope.effects.length > 0
+    || (returnsCallers(g) && (g.envelope.guards.length > 0 || g.envelope.dispatchesOn.length > 0)));
   const entries = routes.map(r => {
     const key = `route:${r.path}`;
     const ee = engEntry.get(key);
     const rs = shapes.get(r.path);
-    const wrapper = rs.shapedByGenerator;
+    const wrapper = wraps(gens.get(rs.shapedByGenerator)) ? rs.shapedByGenerator : null;
     const inst = wrapper ? insts.find(i => i.callerId === rs.handlerId && i.generatorId === wrapper) : null;
     const passed = (inst ? inst.slotBindings : []).filter(sb => ['function', 'effect'].includes(sb.slotRole)).map(sb => ({
       slot: sb.slotName, id: sb.targetId || null, label: sb.targetId ? bare(sb.targetId) : null,
@@ -193,7 +264,13 @@ export function buildSystemMap(engine, { program }) {
       reachKinds: ee.reaches,
       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,
+      // every branch of the entry's own where a path refuses (a wrapper's are
+      // its own, and a function handed to it keeps its own slot)
+      ...(trees.has(key)
+        // one mark per check, though the tree meets it on several paths
+        ? (forks => ({ guards: forks.map(n => forkLabel(n, ownDefs)), guardIds: forks.map(n => forkId(n, ownDefs)), guardParts: forks.map(n => forkParts(n, ownDefs)) }))(uniqBy(trees.get(key).filter(n => n.concern?.layer !== 'cross'
+          && !(inst ? inst.slotBindings : []).some(sb => (sb.guards || []).includes(forkId(n, ownDefs)))), forkKey(ownDefs)))
+        : { guards: rs.handlerGuards.map(bare), guardIds: rs.handlerGuards }),
       wrapper, via: rs.viaSpecialization ? bare(rs.viaSpecialization) : null,
       policy: (inst ? inst.slotBindings : []).filter(s => s.slotRole === 'semantic-object').map(s => s.value).filter(Boolean),
       passed, beside: inst ? besideOf(inst) : null, reach,
@@ -261,7 +338,9 @@ export function buildSystemMap(engine, { program }) {
 
   const present = uniq(st.ioKinds.flatMap(b => b.resources));
   const tables = uniq(entries.flatMap(e => [...e.reach, ...(e.beside ? e.beside.effects : [])].map(r => r.table))).sort();
-  const resources = ['db', 'model', 'net'].filter(k => present.includes(k)).map(k => ({ kind: k, ...(k === 'db' ? { tables } : {}), from: 'structure.ioKinds[].resources' }));
+  const policies = engine.access ? Object.fromEntries(engine.access.report.resources.filter(r => tables.includes(r.resource)).map(r => [r.resource, policyWord(r)])) : null;
+  const resources = ['db', 'model', 'net'].filter(k => present.includes(k)).map(k => ({ kind: k,
+    ...(k === 'db' ? { tables, ...(policies ? { policies, policyFrom: 'access.report.resources[].policyKind, guards, roles' } : {}) } : {}), from: 'structure.ioKinds[].resources' }));
   const ghostResources = ['db', 'model', 'net'].filter(k => !present.includes(k)).map(k => ({ kind: k, from: 'structure.ioKinds[] checked: no site of this kind' }));
 
   const transports = uniq(st.entries.map(e => e.transport));
@@ -355,10 +434,17 @@ export function bundlesOf(entries, uses, keyed) {
 // The paths' shared segments, * where they differ, /** for differing depths.
 export function pathPattern(paths) {
   if (paths.length === 1) return paths[0];
+  const sorted = [...paths].sort();
   const segs = paths.map(p => p.split('/'));
   const n = Math.min(...segs.map(s => s.length));
   const out = [];
-  for (let i = 0; i < n; i++) { const v = uniq(segs.map(s => s[i])); out.push(v.length === 1 ? v[0] : '*'); }
+  const vary = [];
+  for (let i = 0; i < n; i++) { const v = uniq(segs.map(s => s[i])); out.push(v.length === 1 ? v[0] : '*'); if (v.length > 1) vary.push([i, v]); }
+  // one part of the path differs among a few: the title names every route by it, "/{tasks,tags}/sync"
+  if (segs.every(s => s.length === n) && vary.length === 1 && vary[0][1].length <= 6) { const [[i, v]] = vary; out[i] = `{${[...v].sort().join(', ')}}`; }
+  if (segs.every(s => s.length === n) && vary.length <= 1) return out.join('/');
+  // a few routes that differ in more than one part: each by name
+  if (paths.length <= 4) return sorted.join(', ');
   if (segs.every(s => s.length === n)) return out.join('/');
   let k = 0; while (k < n && out[k] !== '*') k++;
   return out.slice(0, Math.max(k, 1)).join('/') + '/**';

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

@@ -163,6 +163,8 @@ export const MARK_KINDS = [...new Set([...Object.values(MARK_KIND), 'resource',
   'reachedBy', 'port', 'plug', 'package', 'chain', 'composes', 'combination', 'generic', 'loop', 'wall',
   // the program band: a pure program, its requests, and the engines that perform them
   'program', 'decision', 'request', 'variant', 'gap', 'wire', 'lane', 'laneFork', 'laneResource', 'replyLoop', 'starter', 'programEffect', 'replaced',
+  // the line under a service map saying its names are the author's labels
+  'names',
   // the what-happens view's (what-happens.js) one new mark: the end of a path
   'outcome'])].sort();
 
@@ -215,7 +217,12 @@ function rack(map, x, y, phone, room, notes = {}, scale = {}) {
     // a present resource drawn at its share of the routes that reach it (1 when nothing is counted)
     const w = w0 * (scale[k] ? scale[k].w : 1), h = h0 * (scale[k] ? scale[k].h : 1);
     if (present) {
-      const tl = k === 'db' ? (present.tables || []) : [];
+      // each table with its access policy; too many to list, the policies counted
+      const pol = k === 'db' ? present.policies : null;
+      const named = k === 'db' ? (present.tables || []) : [];
+      const word = n => pol[n] || 'unchecked';
+      const tl = !pol ? (named.length < 12 ? named : []) : named.length < 12 ? named.map(n => `${n} · ${word(n)}`)
+        : Object.entries(named.reduce((m, n) => ({ ...m, [word(n)]: (m[word(n)] || 0) + 1 }), {})).map(([w, c]) => `${c} ${c === 1 ? 'table' : 'tables'} · ${w}`);
       out.push(tg([`resource:${k}`], shape('resource', resourceGlyph(k, x - w / 2, yy, w, h, phone, false, tl, room))));
       pos.set(k, { x: x - w / 2, cx: x, y0: yy, y1: yy + h, bottom: yy + h });
       const tablesH = tl.length && tl.length < 12 ? tableLines(tl, room, phone).length * (phone ? 11 : 13) + (phone ? 6 : 8) : 0;
@@ -253,13 +260,16 @@ function wallPath(x0, x1, yTop, yBot, openings, gap, r = 14) {
 }
 
 
-// verb and table for a station label: "read · write notes"
+// each table under the verbs used on it: "read moderators, threads · read/write posts"
 const reachLabel = list => {
-  const vs = [...new Set(list.map(e => e.op === 'read' ? 'read' : e.op === 'delete' ? 'delete' : 'write'))];
   const order = ['read', 'write', 'delete'];
-  vs.sort((a, b) => order.indexOf(a) - order.indexOf(b));
-  const ts = [...new Set(list.map(e => e.table))];
-  return `${vs.join(' · ')} ${ts.join(', ')}`;
+  const verb = e => (e.op === 'read' ? 'read' : e.op === 'delete' ? 'delete' : 'write');
+  const groups = new Map();
+  for (const tbl of [...new Set(list.map(e => e.table))]) {
+    const vs = [...new Set(list.filter(e => e.table === tbl).map(verb))].sort((a, b) => order.indexOf(a) - order.indexOf(b)).join('/');
+    groups.set(vs, [...(groups.get(vs) || []), tbl]);
+  }
+  return [...groups].map(([vs, ts]) => `${vs} ${ts.join(', ')}`).join(' · ');
 };
 const writesIn = list => list.some(e => e.op !== 'read');
 // the room for the words under an after band from `from` to the reply bar at
@@ -423,6 +433,8 @@ function renderService(map, W, opts) {
     builtAt.get(k).tags.push(`use:${u.i}`);
   }
   const keyedTypes = ids => [...new Set([...new Set(ids)].filter(id => keyedById.has(id)).flatMap(id => keyedById.get(id).types))];
+  // under a list of checks, each fork names the check it is inside: "can_see on String"
+  const ownedTypes = ids => [...new Set(ids)].filter(id => keyedById.has(id)).map(id => `${keyedById.get(id).label} on ${keyedById.get(id).types.join(',')}`);
   // line k (from 1) under a path at y
   const line = (y, k) => y + (phone ? 14 : 16) + (k - 1) * lead;
   // a wrapper's own station: its tables under its forks, clear of its check's failure stem; then its builder
@@ -460,7 +472,8 @@ function renderService(map, W, opts) {
     let pathLines = wrapped(name, labEnd - lx, { size: fs }), tailOwn = false;
     if (tailW && tw(pathLines[pathLines.length - 1], fs) + tailW > labEnd - lx) {
       const re = wrapped(pathLines[pathLines.length - 1], labEnd - lx - tailW, { size: fs });
-      if (re[re.length - 1].endsWith('…')) tailOwn = true; else pathLines = [...pathLines.slice(0, -1), ...re];
+      // the count goes on a line of its own sooner than cut a name in two at its _ or -
+      if (re[re.length - 1].endsWith('…') || re.slice(0, -1).some(l => /[_-]$/.test(l))) tailOwn = true; else pathLines = [...pathLines.slice(0, -1), ...re];
     }
     const lastW = tailOwn ? -gap : tw(pathLines[pathLines.length - 1], fs);
     const countX = lx + lastW + gap;
@@ -486,7 +499,7 @@ function renderService(map, W, opts) {
     const left = [];
     const guardLines = !e.wrapper && e.guards.length ? wrapped(e._chk.h.text, gx - 7 - x2, { size: fsS }) : [];
     guardLines.forEach(() => left.push('guard'));
-    const guardFork = !e.wrapper && !dense ? forkLines(keyedTypes(e.members.flatMap(m => m.guardIds)), gx + 6 - 3 - x2) : [];
+    const guardFork = !e.wrapper && !dense ? forkLines(ownedTypes(e.members.flatMap(m => m.guardIds)), gx + 6 - 3 - x2) : [];
     guardFork.forEach(() => left.push('guardFork'));
     const tokens = !dense && e.policy.length ? wrapped(e.policy.join(', '), leftEnd - x2, { size: fsS }) : [];
     tokens.forEach(() => left.push('token'));
@@ -519,7 +532,7 @@ function renderService(map, W, opts) {
       built = builtAt.get(`s:${i}`);
       if (built) inner.push('builder');
       if (guardBelow) xpgGuard = wrapped(gname, hx1 - 6 - xPG - 6, { size: fsS });
-      xpgFork = !(p && p.guards.length) ? [] : forkLines(keyedTypes(e.members.flatMap(m => m.passed[0]?.guardIds || [])), hx1 - 6 - (xPG + 4) - 11);
+      xpgFork = !(p && p.guards.length) ? [] : forkLines(ownedTypes(e.members.flatMap(m => m.passed[0]?.guardIds || [])), hx1 - 6 - (xPG + 4) - 11);
       const xpg = xpgGuard.length + xpgFork.length;
       const b = e.beside;
       if (!dense && (b.calls.length || b.effects.length)) {
@@ -581,15 +594,17 @@ function renderService(map, W, opts) {
   // a fork under a mark, its types (when drawn) on line k ending by `end`: the choice is made by the definition drawn there
   // a row's labels hang from its route: bound to it, so they read as its own
   const rowB = (e, svg) => (e ? bound(`route:${e.key}`, svg) : svg);
-  const forkAt = (ids, x, y, k, end, own = 'canvas', anchorEnd = false, row = null) => {
+  // a fork under checks names each check with its type, so two checks on one type stay two
+  const forkAt = (ids, x, y, k, end, own = 'canvas', anchorEnd = false, row = null, checks = anchorEnd) => {
     const ks = [...new Set(ids)].filter(id => keyedById.has(id));
     if (!ks.length) return;
     ks.forEach(id => forkPlaced.add(id));
-    const types = keyedTypes(ks).join(',');
+    const typeList = checks ? ownedTypes(ks) : keyedTypes(ks);
+    const types = forkJoin(typeList);
     const fy = dense ? y + (phone ? 12 : 15) : line(y, k) - 3.5;
     // types with no room even for a letter are the fork's tooltip; else they take the lines they need
     const room = anchorEnd ? x - 3 - end : end - x - 11;
-    const lines = forkLines(keyedTypes(ks), room).filter(Boolean);
+    const lines = forkLines(typeList, room).filter(Boolean);
     const label = dense ? '' : !lines.length ? `<title>${esc(types)}</title>`
       : Tw(anchorEnd ? x - 3 : x + 11, fy + 3.5, lines, { size: fsS, fill: C.muted, ...(anchorEnd ? { anchor: 'end' } : {}) }, types, lead);
     over.push(tg(ks.flatMap(id => [`fork:${id}`, `forkRow:${id}`]), mark.fork(x, fy, phone ? 0.6 : 0.7) + owned(own, rowB(row, label))));
@@ -729,7 +744,7 @@ function renderService(map, W, opts) {
         const gkeys = each(e, m => (m.passed[0]?.guardIds || []).map(g => `guard:${m.key}:passed:${g}`));
         guardAt(gkeys, dense || below ? [] : e._chk.p.names, xPG, y, (hx1 - xPG) * 2 - 8, 0.9, hull, e, svg => checkLabel(e._chk.p, svg));
         if (below) out.push(owned(hull, rowB(e, checkLabel(e._chk.p, Tw(xPG + 6, line(y, 1), xpgGuard, { size: fsS, fill: C.guard }, e._chk.p.text, lead)))));
-        if (xpgFork.length || dense) forkAt(e.members.flatMap(m => m.passed[0]?.guardIds || []), xPG + 4, y, xpgGuard.length + 1, hx1 - 6, hull, false, e);
+        if (xpgFork.length || dense) forkAt(e.members.flatMap(m => m.passed[0]?.guardIds || []), xPG + 4, y, xpgGuard.length + 1, hx1 - 6, hull, false, e, true);
       }
       // past the hull: the after band, then the reply bar
       out.push(`<path${anchorAttr(rowId)} d="M${f1(xSock + rS)} ${y} H${f1(xr)}" stroke="${C.ink2}" stroke-width="${f1(cableW(e))}"/>`);
@@ -873,7 +888,17 @@ function renderService(map, W, opts) {
     }
   }
 
-  const H = Math.max(yBot, R.bottom) + (phone ? 12 : 20);
+  // once, under the picture: the names on it are the author's labels (the record's vocabulary.names)
+  let yEnd = Math.max(yBot, R.bottom);
+  const namesNote = map.vocabulary?.names;
+  if (namesNote && !opts.only && rowsIn.some(e => e.guards.length)) {
+    const lines = wrapped(namesNote, W - 2 * pad, { size: fsS, mono: false });
+    const gap = fsS + 3;
+    yEnd += phone ? 14 : 18;
+    out.push(shape('names', Tw(pad, yEnd, lines, { size: fsS, fill: C.muted, mono: false }, namesNote, gap)));
+    yEnd += (lines.length - 1) * gap;
+  }
+  const H = yEnd + (phone ? 12 : 20);
   return outerFrame(W, H, wall.fill + under.join('') + shape('wall', wall.line) + out.join('') + over.join(''), { ...opts, frameTop }, map.program, opts.crumb);
 }
 
@@ -949,10 +974,8 @@ export function programBand(programs, x0, x1, y0, phone, rows = null) {
     // the counts on one line, or two when the program box is narrow
     // its size in words a reader needs no key for: the package's own definitions, and how many more it uses from elsewhere
     const own = `${p.definitions} definitions in ${p.pkgLabel}`;
-    // which packages they come from, the most used first: three named, the rest counted
-    // (each name stays with its count when the line wraps)
-    const from = p.elsewhere.slice(0, 3).map(x => `${x.label}\u00a0${x.n}`).join(', ') + (p.elsewhere.length > 3 ? `, ${p.elsewhere.length - 3}\u00a0more` : '');
-    const more = p.usesElsewhere ? `uses ${p.usesElsewhere} more from ${p.elsewhere.length} package${p.elsewhere.length === 1 ? '' : 's'}: ${from}` : '';
+    // (which packages, ranked by how often, is an import list, not structure: the map draws what they do)
+    const more = p.usesElsewhere ? `uses ${p.usesElsewhere} more from ${p.elsewhere.length} package${p.elsewhere.length === 1 ? '' : 's'}` : '';
     const defsTxt = more ? `${own} · ${more}` : own;
     const headRoom = cw * (phone ? 0.56 : 0.5) - (phone ? 26 : 34);
     const defsLines = tw(defsTxt, fsS, false) <= headRoom ? [defsTxt] : [own, more].filter(Boolean).flatMap(l => wrapAt(l, headRoom, fsS, false));
@@ -1233,8 +1256,10 @@ function wallPathGaps(x0, x1, yTop, yBot, openings, r = 14) {
 // long for a line clipped where the line ends. Only a type broken mid-word
 // across lines (a line that ends inside a type) with the rest clipped puts
 // the types on one line, clipped.
+// a named fork ("can_see on String") is a phrase, so phrases are set apart by a space too
+const forkJoin = types => types.join(types.some(t => t.includes(' ')) ? ', ' : ',');
 export function forkTypeLines(types, room, size) {
-  const s = types.join(',');
+  const s = forkJoin(types);
   if (!types.length) return [];
   if (room < tw(`${s[0]}…`, size)) return [''];
   const ls = wrapped(s, room, { size });
@@ -1346,8 +1371,19 @@ function placeOn(pkgs, lsx, phone, f, M) {
 // from its tick. One line, however many parts. null when even this would not fit.
 // a gathered set of choices says what they choose on in its own words; anything else is its label
 const setLabel = it => it.kind === 'forkset' ? `${it.label} on ${it.fork.join(', ')}` : it.label;
+// The names rise at 50 degrees; when one would be cut at the wall, they rise
+// more steeply, so a name is cut only when it would be even at the steepest.
 function angledQuiet(pkgs, lsx, lex, y0, phone, fsS) {
-  const ang = 50, sin = Math.sin(ang * Math.PI / 180), cos = Math.cos(ang * Math.PI / 180);
+  let first = null;
+  for (const ang of [50, 55, 60, 65, 70, 75, 80]) {
+    const A = angledQuietAt(ang, pkgs, lsx, lex, y0, phone, fsS);
+    if (A && !A.clipped) return A;
+    first = first || A;
+  }
+  return first;
+}
+function angledQuietAt(ang, pkgs, lsx, lex, y0, phone, fsS) {
+  const sin = Math.sin(ang * Math.PI / 180), cos = Math.cos(ang * Math.PI / 180);
   const pkgName = p => p.split('/').pop();
   // each name as its spans: [text, fill, attributes, how it is measured: mono, weight, italic]
   const upSpans = it => [...(it.gen ? [[`∀${it.gen} `, C.hullInk, ` font-family="${SANS}" font-weight="700"`, false, 700]] : []),
@@ -1414,7 +1450,8 @@ function angledQuiet(pkgs, lsx, lex, y0, phone, fsS) {
       over.push(tg(it.keys, gg));
     });
   }
-  return { items: pkgs.length, under, out, over, bottom: ry + downLen * sin + (phone ? 4 : 6) };
+  const clipped = [...ups.values(), ...downs.values()].some(f => f.full !== null);
+  return { items: pkgs.length, under, out, over, bottom: ry + downLen * sin + (phone ? 4 : 6), clipped };
 }
 
 export function layoutQuiet(pkgs, lsx, lex, y0, phone, fsS0, bands = []) {
@@ -1429,7 +1466,7 @@ export function layoutQuiet(pkgs, lsx, lex, y0, phone, fsS0, bands = []) {
     bands,
     // as drawn: a gathered count and a step set in bold, ∀ in bold sans
     width: (it, f) => Math.max((it.gen ? tw(`∀${it.gen} `, f, false, 700) : 0) + tw(setLabel(it), f, true, it.kind === 'part' ? 400 : 700), tw(sub(it), Math.max(MIN_LABEL, f - 0.5)) + (sub(it) && it.fork ? (phone ? 9 : 12) : 0)) + (it.kind === 'forkset' ? (phone ? 16 : 22) : (phone ? 7 : 10)) + (it.kind === 'stepset' ? (phone ? 9 : 11) : 0),
-    header: (g, f) => tw(g.pkg ? pkgName(g.pkg) : `${g.gathered} packages`, f, false, 700) + (g.exports.length ? (phone ? 9 : 12) + tw(String(g.exports.length), f, true, 700) : 0) + (phone ? 8 : 12),
+    header: (g, f) => tw(g.pkg ? pkgName(g.pkg) : `${g.gathered} ${g.gathered === 1 ? 'package' : 'packages'}`, f, false, 700) + (g.exports.length ? (phone ? 9 : 12) + tw(String(g.exports.length), f, true, 700) : 0) + (phone ? 8 : 12),
     steps: (g, f) => g.steps.length ? Math.max(...g.steps.map(s => tw(s.label, f, true, 700))) + (phone ? 10 : 13) + (phone ? 6 : 8) : 0,
   };
   let L = placeOn(pkgs, lsx, phone, fsS, M);
@@ -1470,7 +1507,7 @@ export function layoutQuiet(pkgs, lsx, lex, y0, phone, fsS0, bands = []) {
       const hy = ry - (phone ? 27 : 33) - tier * (phone ? 10 : 12);
       under.push(`<path d="M${f1(tick)} ${f1(hy + 3)} V${f1(ry + 6)}" stroke="${C.faint}" stroke-width="1"${tier ? '' : ' stroke-dasharray="0"'}/>`);
       if (g.pkg) out.push(T(tick, hy, pkgName(g.pkg), { size: fsS, weight: 700, fill: C.faint, mono: false }));
-      else if (g.gathered) out.push(T(tick, hy, `${g.gathered} packages`, { size: fsS, weight: 700, fill: C.faint, mono: false }));
+      else if (g.gathered) out.push(T(tick, hy, `${g.gathered} ${g.gathered === 1 ? 'package' : 'packages'}`, { size: fsS, weight: 700, fill: C.faint, mono: false }));
       if (g.exports.length) {
         const ex = tick + tw(pkgName(g.pkg), fsS, false, 700) + (phone ? 7 : 9);
         over.push(tg(g.exports.map(id => `entry:${id}`), mark.inHead(ex, hy - fsS * 0.35, phone ? 0.5 : 0.6) + T(ex + (phone ? 2 : 3), hy, String(g.exports.length), { size: fsS, weight: 700, fill: C.ink2 })));

package/dist/studio-page/what-happens-record.js

@@ -20,19 +20,22 @@ export const VOCABULARY = {
   version: MARKS_VERSION,
   added: ['outcome'],
   marks: {
-    entryHead: 'arrowhead where a request comes in; the rack above the tree has one per described entry, then one dashed line counting the entries no scenario describes, which opens to draw each of them struck  <- entries[], ghosts[]',
+    entryHead: 'arrowhead where a request comes in; the rack above the tree has one per described entry, then one dashed line counting the entries no scenario describes, which opens to draw each of them struck (when no entry is described, that one line is all the rack draws, and it only counts them: "8 entries"; a scenario is a requirement someone wrote, so its absence says nothing about tests); under the head, "same steps as …" names the entries whose trees take the same steps on their own tables and checks  <- entries[], ghosts[], entries[].sameShape',
     guard: 'red diamond: the declared sign-in or role check, the first branch of every entry that has one; its failure stem ends in a refusal  <- tree node with from.kind=guard',
-    fork: 'three prongs: a branch the code takes on the request, the caller, a value read from a table, or a call result; the arm each line takes is written where it leaves  <- tree nodes',
-    station: 'ring on a line: an effect on that path, its verb and table beside it; filled = it writes  <- arms[].effects, entry.effects',
+    fork: 'three prongs: a branch the code takes on the request, the caller, a value read from a table, or a call result, with "← request", "← caller" or "← <table> as read" saying where what it tests comes from; the arm each line takes is written where it leaves  <- tree nodes, nodes[].from.sources',
+    docs: 'under the names line, in italic, the comment the author wrote above each named check, marked unchecked: what the author says it decides, which the engine does not confirm  <- docs (structure.docs)',
+    rows: 'under the tree, for each table its stations touch (and those of the entries named in "same steps as"), what one row holds, by its checked type: "posts holds List[Post(id: String, …, edited: Bool)]"; a field that is a record gives only its type\'s name, a choice of bare cases its cases ("visibility: Open | Members")  <- rows (structure.rows)',
+    station: 'ring on a line: an effect on that path, its verb and table beside it; filled = it writes; mint = the platform hands out a fresh row id. Under it, in grey, the row it touches (the caller\'s row; the row named by a request field; one fixed row; a new row; every row, and the guard that keeps them) and, for a write, whether the row is replaced whole or updated from what it read, then where what it writes comes from, field by field (← caller, ← request.<field>, ← a literal, ← new id, ← a call and what it was computed from)  <- arms[].effects[].key, value, kept (access report.findings[operation=keep_visible].provenBy)',
     modelRing: 'violet ring: the path reaches the model  <- effects[resource=model]',
     netRing: 'orange ring: the path reaches the network  <- effects[resource=net]',
     outcome: 'the end of a path: a cap with what the request gets back (a constructor, or a refusal with its status and code); red when a claim fails there or a check reports a witness that ends there, green when every obligation that failed there at the base is checked here and holds, hollow and dashed (unchecked) when a claim there is inconclusive or an obligation that failed at the base is no longer checked, grey otherwise  <- leaves',
     unchecked: 'a hollow dashed cap and a ? tick: the engine cannot say whether the claim holds on this path (a step it could not open, a table it could not name, an answer it could not decide), or what failed here at the base is not checked here; never counted as holding  <- claims[verdict=inconclusive], leaves[].gaps, diff.unresolved',
     struck: 'a struck ghost: something checked and found absent (an entry nobody described, a write a claim says a path must not make)  <- ghosts[], claims holding with not',
     bundle: 'a cable with a count: a subtree too large for this view; opening it draws that part with a breadcrumb  <- derived from the tree',
-    compared: 'a line under the rack, always there: "compared with <base> · N fixed · M still failing", or "no base compared" in faint text  <- diff',
+    compared: 'a line under the rack when a base was compared: "compared with <base> · N fixed · M still failing"; with no base, no line  <- diff',
     hull: 'a shaded box on the line: a step that is not the handler\'s own work, folded (a wrapper\'s guard or short-circuit, the platform\'s declared check or the transaction it runs the plan in, work beside the wrapper, a wrapper\'s work after the handler); it keeps what the step answers instead of running the handler: the effects it makes before its test above the arms, then one row per arm read as a side stub (the arm, the effects that arm makes, its struck writes, what the request gets, ticks), then "continue"; opening it draws the step\'s own tree; drawn inline, the same hull is a light band behind the step and its exits, with its role and where it comes from above its test, so either way it reads as not the handler\'s own work  <- tree nodes[concern.role], entries[].steps',
   },
+  names: 'every check, call and table name is a label the code\'s author (often an AI) chose; the picture proves where a check runs, what it is given and what happens when it fails, never what it decides: a reader who doubts the author reads that rule itself.',
   rule: 'every entry, branch, arm, effect and outcome the engine computes is drawn, a folded step\'s inside its box and an undescribed entry behind the rack\'s one line; the author\'s words appear only on ids the engine computed, in italic, with the code name beside them.',
   concerns: 'where each branch and effect comes from in value flow (concern.layer, effects[].layer): core = the handler\'s own work, a function it hands its wrapper or its body when it has none; cross = the wrapper its route shape names, shared with other entries; beside = the handler\'s code outside the wrapper call; platform = the route\'s declared authority, or the transaction the platform runs a plan in (its arms that give up or cannot confirm skip the handler\'s work). Roles come from which arms reach the handler, never from names.',
 };
@@ -104,6 +107,14 @@ export function buildWhatHappens(engine, { program, base = null, baseLabel = 'ba
   const claims = st.claims || { scenarios: [], undescribed: (st.scenarios || []).map(s => s.entry) };
   const byEntry = new Map(claims.scenarios.filter(s => s.status === 'matched').map(s => [s.entry, s]));
   const routes = new Map((st.entries || []).map(e => [e.entry, e]));
+  // a query's rows the access check proves are kept only where a guard
+  // holds (report.findings[operation=keep_visible, kind=GuardProven])
+  const kept = new Map((engine.access?.report?.findings || []).filter(f => f.operation === 'keep_visible' && f.kind === 'GuardProven' && f.status === 'holds')
+    .map(f => [`${f.package}::${f.binding}\u0000${f.resource}`, `${(f.provenBy || []).join(' and ')} passes for the caller and the row`]));
+  const withKept = es => es.map(e => {
+    const by = e.kind === 'DbQuery' && e.tables.length === 1 ? kept.get(`${e.site}\u0000${e.tables[0]}`) : null;
+    return by ? { ...e, kept: by } : e;
+  });
   const entries = st.scenarios.map(s => {
     const meta = routes.get(s.entry) || {};
     const sc = byEntry.get(s.entry);
@@ -112,17 +123,31 @@ export function buildWhatHappens(engine, { program, base = null, baseLabel = 'ba
     const copy = t => {
       if (!t) return null;
       if (t.kind === 'leaf') return { ...t, words: names.get(t.id) || null, claims: [], witnesses: [], status: 'grey' };
-      return { ...t, words: names.get(t.id) || null, arms: t.arms.map(a => ({ ...a, words: names.get(a.id) || null, next: copy(a.next) })) };
+      return { ...t, words: names.get(t.id) || null, arms: t.arms.map(a => ({ ...a, effects: withKept(a.effects), words: names.get(a.id) || null, next: copy(a.next) })) };
     };
     return {
       entry: s.entry, handler: s.handler, label: s.entry.replace(/^route:/, ''),
       authority: meta.authority || null, transport: meta.transport || null,
       title: sc?.title || null, described: !!sc,
-      effects: s.effects, tree: copy(s.tree), leafCount: Number(s.leafCount), truncated: s.truncated, unsupported: s.unsupported || null,
+      effects: withKept(s.effects), tree: copy(s.tree), leafCount: Number(s.leafCount), truncated: s.truncated, unsupported: s.unsupported || null,
       wrapper: s.wrapper || null, steps: s.steps || [],
       from: 'structure.scenarios[]',
     };
   });
+  // entries whose trees take the same steps in the same order and end the
+  // same ways, whatever tables and checks they name, share a shape
+  const shapeOf = e => {
+    const eff = x => `${x.op}${x.key ? `@${x.key.kind}` : ''}${x.value ? `<${x.value.kind}` : ''}${x.kept ? '|kept' : ''}`;
+    const go = t => (!t ? '' : t.kind === 'leaf' ? `(${t.outcome.kind}:${(t.outcome.statuses || (t.outcome.status ? [t.outcome.status] : [])).join('/')})`
+      : `[${t.from.kind}${t.arms.map(a => `{${a.effects.map(eff).join(',')}${go(a.next)}}`).join('')}]`);
+    return `${(e.effects || []).map(eff).join(',')}${go(e.tree)}`;
+  };
+  const byShape = new Map();
+  for (const e of entries) byShape.set(shapeOf(e), [...(byShape.get(shapeOf(e)) || []), e.entry]);
+  for (const e of entries) {
+    const same = byShape.get(shapeOf(e)).filter(x => x !== e.entry);
+    if (same.length) e.sameShape = { entries: same, from: 'derived: entries[] trees equal in node kinds, arms, effect verbs, row keys and value kinds, and outcomes' };
+  }
   const entryOf = new Map(entries.map(e => [e.entry, e]));
   const leafById = new Map(entries.flatMap(e => leavesOf(e.tree).map(l => [l.id, l])));
 
@@ -194,6 +219,11 @@ export function buildWhatHappens(engine, { program, base = null, baseLabel = 'ba
   return {
     schema: SCHEMA, marks: MARKS_VERSION, vocabulary: VOCABULARY, program,
     entries, ghosts, claims: checked, witnesses, notes, refused, mismatches, diff,
+    // the comment above each definition, as its author wrote it (structure.docs); never checked
+    docs: (callees => Object.fromEntries(Object.entries(st.docs || {}).filter(([id]) => callees.has(id))))(
+      new Set(entries.flatMap(e => { const ids = []; walk(e.tree, n => { if (n.kind === 'node' && n.from?.kind === 'call') ids.push(n.from.callee); }); return ids; }))),
+    // what each table holds, by its checked row type (structure.rows)
+    rows: Object.fromEntries(Object.entries(st.rows || {}).map(([table, schema]) => [table, rowShape(schema)])),
     counts: { entries: entries.length, described: entries.length - ghosts.length, leaves: leafById.size,
       steps: entries.reduce((n, e) => n + e.steps.length, 0), wrapped: entries.filter(e => e.wrapper && e.wrapper.wraps).length,
       red: [...leafById.values()].filter(l => l.status === 'red').length, green: [...leafById.values()].filter(l => l.status === 'green').length,
@@ -203,6 +233,20 @@ export function buildWhatHappens(engine, { program, base = null, baseLabel = 'ba
 }
 
 // Small helpers the renderer and tests share.
+// A table's row type in a line: List[Post(id: String, edited: Bool)]; a
+// field that is itself a record, or a choice whose cases carry fields,
+// gives only its type's name; a choice of bare cases gives its cases.
+const typeName = s => (s.type ? s.type.split('::').pop() : null);
+const fieldType = s => ({ string: 'String', int: 'Int', float64: 'Float64', bool: 'Bool', unit: 'Unit', json: 'Json' })[s.kind]
+  || (s.kind === 'list' ? `List[${fieldType(s.element)}]` : s.kind === 'unsupported' ? s.rendered
+    // a choice of bare cases is its cases: Open | Members
+    : s.kind === 'union' && s.variants.length && s.variants.every(v => !v.fields.length) ? s.variants.map(v => v.tag).join(' | ') : typeName(s));
+export function rowShape(s) {
+  if (s.kind === 'list') return `List[${rowShape(s.element)}]`;
+  if (s.kind === 'struct') return `${typeName(s)}(${s.fields.map(f => `${f.name}: ${fieldType(f)}`).join(', ')})`;
+  if (s.kind === 'union') return s.variants.map(v => (v.fields.length ? `${v.tag}(${v.fields.map(f => `${f.name}: ${fieldType(f)}`).join(', ')})` : v.tag)).join(' | ');
+  return fieldType(s);
+}
 export const isWriteOp = op => !['read', 'runs', 'effect', 'random', 'trace', 'capture', 'init', 'mint id'].includes(op) && op !== 'call model' && op !== 'fetch article';
 export function stationLabel(e) {
   const verb = e.op === 'mint id' ? 'mint' : e.op;
@@ -210,6 +254,46 @@ export function stationLabel(e) {
   if (e.resource === 'model' || e.resource === 'net') return verb;
   return `${verb} · ${bare(e.primitive)}`;
 }
+// Where a value came from (effects[].key, effects[].value), in a few words:
+// the caller, a request field, a fixed literal, what a read or a new id
+// gave, or a call and what it was computed from.
+export const fromWord = w => (w === 'caller' ? 'caller' : w === 'request' ? 'request' : w.startsWith('mint id:') ? 'new id'
+  : w.startsWith('read:') ? `${w.slice(5)} as read` : w);
+export function sourceText(f) {
+  switch (f.kind) {
+    case 'caller': return 'caller';
+    case 'request': return ['request', ...(f.path || [])].join('.');
+    case 'literal': return f.text;
+    case 'read': return f.op === 'mint id' ? 'new id' : `${f.table || bare(f.primitive)} as read${f.path?.length ? `.${f.path.join('.')}` : ''}`;
+    case 'call': return `${bare(f.callee)}(${(f.from || []).map(fromWord).join(', ')})${f.path?.length ? `.${f.path.join('.')}` : ''}`;
+    case 'built': return f.fields ? `${f.ctor}(${f.fields.map(x => `${x.name} ← ${sourceText(x.from)}`).join(', ')})` : `${f.ctor}(${(f.from || []).map(fromWord).join(', ')})`;
+    case 'derived': return (f.from || []).map(fromWord).join(', ') || 'computed';
+    default: return 'computed';
+  }
+}
+// The row a station touches and, for a write, whether the row it writes
+// carries what it read from that table (an update) or not (a replacement).
+export function rowText(e) {
+  if (!e.key) return e.value ? 'adds a row' : null;
+  const k = e.key;
+  return k.kind === 'caller' ? "the caller's row" : k.kind === 'literal' ? `one fixed row ${k.text}`
+    : k.kind === 'read' && k.op === 'mint id' ? 'a new row' : `the row named by ${sourceText(k)}`;
+}
+const readsOwn = (v, table) => {
+  if (!v) return false;
+  if (v.kind === 'read') return v.table === table && v.op !== 'mint id';
+  if (v.fields) return v.fields.some(x => readsOwn(x.from, table));
+  return (v.from || []).includes(`read:${table}`);
+};
+export function stationDetail(e) {
+  if (e.kind === 'DbQuery') return `every row${e.kept ? `, kept only where ${e.kept}` : ''}`;
+  const row = rowText(e);
+  if (!row) return null;
+  if (!e.value) return row;
+  const fresh = !e.key || e.key.kind === 'read' && e.key.op === 'mint id';
+  const mode = fresh ? '' : readsOwn(e.value, e.tables[0]) ? ' · updated from what it read' : ' · replaced whole';
+  return `${row}${mode} ← ${sourceText(e.value)}`;
+}
 // an unknown answer a station gave back (outcome.from), or a field of it,
 // said in the station's words; any other answer keeps its key
 const said = f => {