yichus 0.3.0 → 0.3.1

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

@@ -22,7 +22,7 @@ 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[]',
@@ -39,7 +39,7 @@ export const VOCABULARY = {
     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',
@@ -62,7 +62,7 @@ export const VOCABULARY = {
     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 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',
+    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[]',

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

@@ -269,6 +269,11 @@ const afterRoom = (b, from, xr) => {
   return b.guards.length ? xr - 2 - (from + (xr - from) / (n + 1)) - 6 : xr - from - 8;
 };
 
+// A hull's right wall on each path that leaves it, where the wrapper returns:
+// whatever the path passes after it runs after the wrapper.
+const hullWall = (x, ys, phone) =>
+  `<path d="${ys.map(y => `M${f1(x)} ${f1(y - (phone ? 8 : 10))} V${f1(y + (phone ? 8 : 10))}`).join(' ')}" stroke="${C.hullInk}" stroke-width="3"/>`;
+
 export function renderSystemMap(map, opts = {}) {
   const W = opts.width || 1100;
   return inFrame(W, () => map.kind === 'service' ? renderService(map, W, opts) : renderLibrary(map, W, opts));
@@ -678,7 +683,8 @@ function renderService(map, W, opts) {
     const first = members[0], last = members[members.length - 1];
     const hy0 = Math.min(...ys) - (phone ? 20 : 24) - first._lay.lift, hy1 = Math.max(...ys) + (phone ? 18 : 22) + lead * Math.max(0, last._lay.lines - 1);
     const hull = `hull:${w.id}`;
-    under.push(tg([`wrapper:${w.id}`], `<g data-mark="hull"${opener(w.id, `Open ${w.label}`)}><rect x="${f1(hx0)}" y="${f1(hy0)}" width="${f1(hx1 - hx0)}" height="${f1(hy1 - hy0)}" rx="${phone ? 9 : 13}" fill="${C.hull}" stroke="${C.hullEdge}" stroke-width="1.2"${boxAttr(hull)}/></g>`));
+    under.push(tg([`wrapper:${w.id}`], `<g data-mark="hull"${opener(w.id, `Open ${w.label}`)}><rect x="${f1(hx0)}" y="${f1(hy0)}" width="${f1(hx1 - hx0)}" height="${f1(hy1 - hy0)}" rx="${phone ? 9 : 13}" fill="${C.hull}" stroke="${C.hullEdge}" stroke-width="1.2"${boxAttr(hull)}/>` +
+      hullWall(hx1, ys, phone) + '</g>'));
     { const { ha, lines } = hullTitle.get(w.id);
       out.push(Tw(ha, hy0 - (phone ? 4 : 5), lines, { size: titleSz, weight: 700, fill: C.hullInk }, w.label, lineGap(titleSz), 'up')); }
     for (const e of members) {
@@ -893,6 +899,10 @@ export const wrapAt = (text, width, size, mono = true) => {
   return lines;
 };
 const RES_WORD = { db: 'db', model: 'model', net: 'net', compile: 'compile', run: 'run', io: 'io' };
+// A lane is named by its package, and by its own definition where another lane shares that package.
+export const laneName = (program, engine) =>
+  (program.engines.some(x => x !== engine && x.pkg === engine.pkg) ? `${engine.pkgLabel}.${engine.label}` : engine.pkgLabel);
+
 export function programBand(programs, x0, x1, y0, phone, rows = null) {
   const under = [], out = [], over = [];
   // a label that fits the room it is given: shrunk a little, then cut, with
@@ -997,10 +1007,11 @@ export function programBand(programs, x0, x1, y0, phone, rows = null) {
     // what an engine does, from its type: what it takes of the program's own and what its effect yields; its code name on hover
     // (the arrow stays with what it gives, so a wrapped line never ends on it)
     const sigOf = e => `${e.type.plainTakes.join(', ') || '()'} →\u00a0${e.type.yields}`;
+    const nameOf = e => laneName(p, e);
     const codeOf = e => `${e.label}: ${e.type.takes.join(', ')} → ${e.type.returns}`;
     // above each lane: its package, then what it does on at most two lines, when every lane's words fit there
     const sigLines = e => wrapAt(sigOf(e), spacing - 6, fsS);
-    const wide = p.engines.every(x => tw(x.pkgLabel, fsS) <= spacing - 6 && sigLines(x).length <= 2 && sigLines(x).every(l => tw(l, fsS) <= spacing - 6));
+    const wide = p.engines.every(x => tw(nameOf(x), fsS) <= spacing - 6 && sigLines(x).length <= 2 && sigLines(x).every(l => tw(l, fsS) <= spacing - 6));
     const laneTop = top + headH - (phone ? 6 : 8);
     const resH = phone ? 15 : 18, resGap = phone ? 4 : 5;
     const laneBot = Math.max(bot, openY.length ? openY[openY.length - 1] + 14 : bot, ...p.engines.map(e => laneTop + barH(e.decisions) + 8));
@@ -1017,7 +1028,9 @@ export function programBand(programs, x0, x1, y0, phone, rows = null) {
       const how = e.loop.kind === 'repeat' ? `${e.loop.label} repeats the round` : e.loop.kind === 'recursion' ? `${e.loop.label} calls itself, a round each time` : 'rounds written out one after another';
       const reply = `replies ${e.replies.map(rs => RES_WORD[rs]).join(', ')}`;
       const lines = [];
-      if (!wide) lines.push([`${i + 1} ${e.pkgLabel}: ${sigOf(e)}`]);
+      // a name too long for its room breaks after its package, so the definition that tells lanes apart stays whole
+      if (!wide && nameOf(e) !== e.pkgLabel && tw(`${i + 1} ${nameOf(e)}:`, fsS) > capRoom(i)) lines.push([`${i + 1} ${e.pkgLabel}.`], [`${e.label}: ${sigOf(e)}`]);
+      else if (!wide) lines.push([`${i + 1} ${nameOf(e)}: ${sigOf(e)}`]);
       lines.push(phone ? [how] : [`${how} · ${reply}`]);
       if (phone && e.replies.length) lines.push([reply]);
       if (e.starters.length) lines.push([`each call of ${e.starters.map(k => k.replace(/^route:/, '')).join(', ')} runs ${e.loop.kind === 'sequence' ? 'them' : 'it'}`, e.starters.map(k => `starter:${p.id}:${k}`)]);
@@ -1106,7 +1119,7 @@ export function programBand(programs, x0, x1, y0, phone, rows = null) {
       // its package and name above the lane, or a number when the lanes are close
       if (wide) {
         const sl = sigLines(e), ly0 = laneTop - (phone ? 5 : 6) - (sl.length - 1) * lead;
-        out.push(tg([`lane:${e.id}`, `engineType:${e.id}`], `<g><title>${esc(codeOf(e))}</title>` + T(lx, ly0 - lead, e.pkgLabel, { anchor: 'middle', size: fsS, fill: C.muted }) +
+        out.push(tg([`lane:${e.id}`, `engineType:${e.id}`], `<g><title>${esc(codeOf(e))}</title>` + T(lx, ly0 - lead, nameOf(e), { anchor: 'middle', size: fsS, fill: C.muted }) +
           sl.map((l, j) => T(lx, ly0 + j * lead, l, { anchor: 'middle', size: fsS, weight: 700, fill: C.ink })).join('') + '</g>'));
       } else out.push(tg([`lane:${e.id}`, `engineType:${e.id}`], `<g><title>${esc(codeOf(e))}</title>` + T(lx, laneTop - (phone ? 5 : 6), String(i + 1), { anchor: 'middle', size: fsS, weight: 700, fill: C.ink }) + '</g>'));
       // the engine's own decisions, on the program's scale; its bar gives up width so that the count fits before the next lane
@@ -1986,7 +1999,7 @@ function renderPart(map, partId, opts) {
   const yBot = railUses.length ? busY + (phone ? 18 : 22) : rowsBottom + (phone ? 46 : 52);
   const wall = wallPath(x0, x1, yTop, yBot, ys.concat(railUses.length ? [busY] : []), phone ? 6 : 7);
   const casing = part.station ? 'canvas' : 'casing';
-  if (!part.station) under.push(shape('hull', `<rect x="${x0 + 8}" y="${yTop + 8}" width="${f1(caseEnd - x0 - 8)}" height="${yBot - yTop - 16}" rx="12" fill="${C.hull}" stroke="${C.hullEdge}" stroke-width="1"${boxAttr(casing)}/>`));
+  if (!part.station) under.push(shape('hull', `<rect x="${x0 + 8}" y="${yTop + 8}" width="${f1(caseEnd - x0 - 8)}" height="${yBot - yTop - 16}" rx="12" fill="${C.hull}" stroke="${C.hullEdge}" stroke-width="1"${boxAttr(casing)}/>` + hullWall(caseEnd, ys, phone)));
   // a fork under a mark, its types from line k ending by `end`
   const forkAt = (ids, x, y, k, end) => {
     const ks = keyed(ids);

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

@@ -28,10 +28,10 @@ export const VOCABULARY = {
     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, "no base compared" when no earlier version was compared)  <- ghosts[], claims holding with not',
+    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", struck  <- 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, one row per arm that skips the handler, read as a side stub (the arm, its struck writes, what the request gets, ticks), then "continue" (a transaction: "runs"), and its effects; 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',
+    compared: 'a line under the rack, always there: "compared with <base> · N fixed · M still failing", or "no base compared" in faint text  <- 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',
   },
   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.',
@@ -210,8 +210,15 @@ export function stationLabel(e) {
   if (e.resource === 'model' || e.resource === 'net') return verb;
   return `${verb} · ${bare(e.primitive)}`;
 }
+// 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 => {
+  if (f.kind !== 'read') return null;
+  const gives = `what ${f.op} · ${f.table || bare(f.primitive)} gives back`;
+  return f.path && f.path.length ? `the ${f.path.join('.')} of ${gives}` : gives;
+};
 export function outcomeLabel(o) {
   if (o.status && !o.constructors.length) return o.shown;
-  const head = o.constructors.length ? o.constructors.join(' | ') : (o.value ? `the ${o.value}` : o.shown);
+  const head = o.constructors.length ? o.constructors.join(' | ') : ((o.from && said(o.from)) || (o.value ? `the ${o.value}` : o.shown));
   return head;
 }

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

@@ -3,7 +3,7 @@
 // copies from the engine. It never measures code.
 //
 //   renderWhatHappens(record, { width, entry, open, cross, ghosts })   any width; 390 and 1100 are tuned
-//   renderNotes(record)                                  the author's text that is not a claim (HTML, outside the frame)
+//   renderNotes(record, entry)                           the author's text that is not a claim about that entry (HTML, outside the frame)
 //
 // The tree is the journey view's metro line turned on its side: a request
 // comes in at the top and runs down. The path that reaches the main outcome
@@ -41,7 +41,7 @@
 // (poteto) TLA+ diagrams.
 
 import { mark, tg, MIN_LABEL, COLORS as C } from './system-map.js';
-import { leavesOf, pathEffects, allEffects, stationLabel, outcomeLabel, isWriteOp } from './what-happens-record.js';
+import { walk, leavesOf, pathEffects, allEffects, stationLabel, outcomeLabel, isWriteOp } from './what-happens-record.js';
 import { SANS, MONO, textWidth, clipText, boxAttr, fitAttr, labelAttr, labelled } from './label-fit.js';
 
 const RED = C.guard, GREEN = '#1f7a45', GREEN_SOFT = '#e4f4ea', RED_SOFT = '#fbe9e7';
@@ -109,32 +109,45 @@ export function foldOf(t) {
   const go = t.arms.filter(a => a.handler), skip = t.arms.filter(a => !a.handler);
   return go.length === 1 && skip.length ? { go: go[0], skip } : null;
 }
-// the status and codes, less what the label already says
+// the statuses a path can be refused with: one, several, or none
+const statusesOf = o => o.statuses || (o.status ? [o.status] : []);
+// the status and codes, less what the label already says; an answer that
+// may instead be refused says with what
 const shortDetail = o => {
-  const head = outcomeLabel(o);
-  return [o.status && !head.includes(String(o.status)) ? String(o.status) : '', ...o.codes.filter(c => !head.split(' ').includes(c))].filter(Boolean).join(' ');
+  const head = outcomeLabel(o), statuses = statusesOf(o).filter(s => !head.includes(String(s)));
+  const detail = [statuses.join(' or '), ...o.codes.filter(c => !head.split(' ').includes(c))].filter(Boolean).join(' ');
+  return o.kind !== 'refused' && detail ? `or refused ${detail}` : detail;
 };
+// A refusal with no status is a transaction that did not commit: its writes
+// are undone and the value goes back as the request's answer, not as an
+// error status.
+const refusedWord = o => (o.kind !== 'refused' ? '' : statusesOf(o).length ? 'refused ' : 'undone · answers ');
 const outcomeText = o => {
   const head = outcomeLabel(o), detail = shortDetail(o);
-  return `${o.kind === 'refused' ? 'refused ' : ''}${head}${detail ? ` ${detail}` : ''}`;
+  return `${refusedWord(o)}${head}${detail ? ` ${detail}` : ''}`;
 };
 // What a folded step can answer instead of running the handler: one row per
-// arm that skips it, read as a side stub reads (the arm, the writes a claim
-// says it does not make, struck, then what the request gets, its witness
-// number and the claims' ticks), then "continue" (a transaction: "runs").
+// arm that skips it, read as a side stub reads (the arm, the effects it runs,
+// the writes a claim says it does not make, struck, then what the request
+// gets, its witness number and the claims' ticks), then "continue".
 // A skip that is not a refusal still ends the request there: "ends Denied".
 const humane = p => p.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
 const absentOf = l => l.claims.filter(holdsAbsent).map(c => {
   const { is: verb, subject: table } = c.property;
   return `${verb === 'writes' ? 'write' : 'read'} · ${table}`;
 });
-const endText = o => (o.kind === 'refused' ? outcomeText(o) : `ends ${outcomeLabel(o)}`);
+const endText = o => (o.kind === 'refused' ? outcomeText(o) : `ends ${outcomeText(o)}`);
+// a step's own effects: not the handler's work, and not a wrapper's work after it
+const notCore = e => !isCore(e) && e.phase !== 'after';
+// the effects an arm runs that are not the handler's own work, on it and under it
+const skippedEffects = a => { const out = [...a.effects]; walk(a.next, x => { if (!x.kind) out.push(...x.effects); }); return out.filter(notCore); };
 export function foldArms(t, witnessNo = new Map()) {
   const f = foldOf(t);
   if (!f) return null;
   const rows = f.skip.map(a => {
     const ls = leavesOf(a.next);
     const segs = [{ text: a.words || (a.pattern === '_' ? 'otherwise' : t.from && t.from.kind === 'platform' ? humane(a.pattern) : a.pattern), italic: !!a.words, mono: !a.words, fill: a.words ? C.ink : C.muted }];
+    for (const w of [...new Set(skippedEffects(a).map(stationLabel))]) segs.push({ text: w, fill: C.hullInk });
     for (const w of [...new Set(ls.flatMap(absentOf))]) segs.push({ text: w, struck: true, fill: C.faint });
     segs.push({ text: '→', mono: false, fill: C.faint });
     ls.forEach((l, i) => {
@@ -145,7 +158,7 @@ export function foldArms(t, witnessNo = new Map()) {
     });
     return segs;
   });
-  return [...rows, [{ text: t.from && t.from.kind === 'platform' ? f.go.arm : 'continue', fill: C.ink2 }]];
+  return [...rows, [{ text: 'continue', fill: C.ink2 }]];
 }
 export function foldOutcomes(t) {
   const rows = foldArms(t);
@@ -157,6 +170,8 @@ function armInto(tree, node) {
   go(tree);
   return hit;
 }
+// the effects a step makes before its test: on the way into it
+const incomingOf = (entry, node) => ((armInto(entry.tree, node) || entry).effects || []).filter(notCore);
 const effectKey = e => `${e.primitive}|${e.site}|${e.line}|${e.tables.join(',')}|${e.phase || ''}`;
 function findNode(tree, id) {
   let hit = null;
@@ -220,8 +235,12 @@ export function renderWhatHappens(record, opts = {}) {
   // the folded steps: each node step's effects go in its box, and so do a
   // wrapper's effects after the handler and the work beside it
   P.paths = pathEffects(entry);
-  P.steps = new Map((entry.steps || []).filter(st => st.node).map(st => [st.node, st]));
-  P.hidden = new Set((entry.steps || []).filter(st => !st.node || foldOf(findNode(entry.tree, st.node))).flatMap(st => st.effects.map(effectKey)));
+  // a folded step draws the effects on its way in; its skip arms are not drawn
+  P.hidden = new Set((entry.steps || []).flatMap(st => {
+    if (!st.node) return st.effects;
+    const n = findNode(entry.tree, st.node);
+    return foldOf(n) ? incomingOf(entry, n) : [];
+  }).map(effectKey));
   const x0 = P.pad + (phone ? 6 : 12);
   y = entryHead(entry, root || stepNode, record, P, x0, y, out, opts.open);
   const subject = root ? root.next : stepNode || entry.tree;
@@ -297,8 +316,7 @@ function rack(record, selected, P, y, out, expanded) {
 function compared(record, P, y, out) {
   const x = P.pad + (P.phone ? 6 : 12), d = record.diff;
   if (!d) {
-    const text = 'no base compared', w = width(text, P.fsS, false);
-    out.push(tg(['compared:none'], `<g${labelAttr('compared')}>${title('no earlier version of the program was compared, so nothing here says what was fixed')}${T(x, y, text, { size: P.fsS, fill: C.faint, mono: false })}${shape('struck', `<path d="M${f1(x - 1)} ${f1(y - 3.5)} H${f1(x + w + 1)}" stroke="${C.faint}" stroke-width="1.1"/>`)}</g>`));
+    out.push(tg(['compared:none'], `<g${labelAttr('compared')}>${title('no earlier version of the program was compared, so nothing here says what was fixed')}${T(x, y, 'no base compared', { size: P.fsS, fill: C.faint, mono: false })}</g>`));
     return y + 4;
   }
   const parts = [[`compared with ${d.base}`, C.muted, null], [`${d.fixed.length} fixed`, d.fixed.length ? GREEN : C.muted, 600], [`${d.stillRed.length} still failing`, d.stillRed.length ? RED : C.muted, 600]];
@@ -362,15 +380,16 @@ function stations(effects, x, y, P, out, key) {
 // One subtree from (x, y) down. Returns the y where it ends.
 // A folded step: one shaded box on the line (the map's hull), its role,
 // what it answers instead of running the handler, and its effects.
-function foldBox(x, y, P, out, { key, role, head, outs, effects, open }) {
+function foldBox(x, y, P, out, { key, role, head, before = [], outs, effects = [], open }) {
   const lx = x + (P.phone ? 13 : 16), room = P.W - P.pad - lx - 10;
   const lh = P.row * 0.82, fs = P.fsS;
   // each row is a list of pieces laid out left to right; a piece that does
   // not fit starts the next line, indented
   const rows = [];
   for (const l of lines(head, fs, room - 8, false, 3, 700)) rows.push([{ text: l, fill: C.hullInk, weight: 700, mono: false }]);
+  const pre = [...new Set(before.map(stationLabel))], eff = [...new Set(effects.map(stationLabel))];
+  if (pre.length) for (const l of lines(pre.join(', '), fs, room, true, 2)) rows.push([{ text: l, fill: C.hullInk }]);
   for (const o of outs) rows.push(typeof o === 'string' ? [{ text: o, fill: C.ink2 }] : o);
-  const eff = [...new Set((effects || []).map(stationLabel))];
   if (eff.length) for (const l of lines(eff.join(', '), fs, room, true, 2)) rows.push([{ text: l, fill: C.hullInk }]);
   const placed = [];
   let line_ = 0, wMax = 0;
@@ -398,7 +417,7 @@ function foldBox(x, y, P, out, { key, role, head, outs, effects, open }) {
     if (strike) g += shape('struck', `<path d="M${f1(px)} ${f1(py - 3.5)} H${f1(px + p.w)}" stroke="${C.faint}" stroke-width="1"${labelAttr(strike)}/>`);
   }
   const said = outs.map(o => (typeof o === 'string' ? o : o.map(x => (x.struck ? `no ${x.text}` : x.text)).join(' ')));
-  const what = `${head}: ${said.join('; ')}${eff.length ? `; ${eff.join(', ')}` : ''}`;
+  const what = `${head}: ${pre.length ? `${pre.join(', ')}; ` : ''}${said.join('; ')}${eff.length ? `; ${eff.join(', ')}` : ''}`;
   out.push(tg([`fold:${key}`], `<g data-fold="${esc(key)}" data-role="${esc(role)}"${open ? opener(open, `Open ${what}`) : ''}>${title(what)}${g}</g>`));
   return top + h + P.row * 0.35;
 }
@@ -418,9 +437,9 @@ function tree(t, depth, x, y, P, out, entry, top) {
   const f = P.cross === 'folded' && P.stepRoot !== t.id ? foldOf(t) : null;
   if (f) {
     const [role, where] = stepParts(t);
-    const effects = P.steps.get(t.id)?.effects || [];
+    const before = incomingOf(entry, t);
     y = foldBox(x, y, P, out, { key: t.id, role: t.concern.role, head: `${role} · ${t.words || t.test} · ${where}`,
-      outs: foldArms(t, P.witnessNo), effects, open: `step:${t.id}` });
+      before, outs: foldArms(t, P.witnessNo), open: `step:${t.id}` });
     y = stations(f.go.effects, x, y, P, out, f.go.id);
     return sub(f.go, depth + 1, x, y, P, out, entry);
   }
@@ -530,7 +549,7 @@ function stub(a, x, y, P, out, guard) {
   const head = outcomeLabel(l.outcome), detail = shortDetail(l.outcome);
   const no = P.witnessNo.get(l.id), badge = no ? ` [${no}]` : '';
   const color = statusInk(l.status);
-  const tt = clip(`${refused ? 'refused ' : ''}${head}${badge}`, P.fsS, right - lx - 30);
+  const tt = clip(`${refusedWord(l.outcome)}${head}${badge}`, P.fsS, right - lx - 30);
   const ox = place(18 + width(tt, P.fsS, true));
   let g = outcomeMark(ox + 7, cy, l.status, refused, s) + T(ox + 18, cy + 3.5, tt, { size: P.fsS, fill: color, weight: 600 });
   if (detail) g += T(place(width(detail, P.fsS, true)), cy + 3.5, detail, { size: P.fsS, fill: C.muted });
@@ -541,7 +560,7 @@ function stub(a, x, y, P, out, guard) {
   if (l.status === 'green' && l.base) {
     cy += P.row * 0.85;
     const extra = l.base.effects.filter(e => !(P.paths.get(l.id) || []).some(h => h.op === e.op && h.tables.join() === e.tables.join())).map(stationLabel);
-    const btxt = clip(`base: ${l.base.outcome.kind === 'refused' ? 'refused ' : ''}${outcomeLabel(l.base.outcome)}${extra.length ? ` after ${extra.join(', ')}` : ''}`, P.fsS, right - lx - 14);
+    const btxt = clip(`base: ${refusedWord(l.base.outcome)}${outcomeLabel(l.base.outcome)}${extra.length ? ` after ${extra.join(', ')}` : ''}`, P.fsS, right - lx - 14);
     g += `<g data-f="${encodeURIComponent(`base:${l.id}`)}">${title('the same leaf at the base, where it was red')}${outcomeMark(lx + 4, cy, 'red', l.base.outcome.kind === 'refused', s * 0.8, true)}${T(lx + 13, cy + 3.5, btxt, { size: P.fsS, fill: RED, opacity: 0.6 })}</g>`;
   }
   out.push(line(x, y - 2, x, cy + P.row * 0.45));
@@ -608,7 +627,7 @@ function leaf(l, x, y, P, out) {
   const badge = no ? ` [${no}]` : '';
   const claimsText = claimsTextOf(l);
   let g = outcomeMark(x, cy, l.status, refused, s);
-  const t1 = clip(`${refused ? 'refused ' : ''}${head}${badge}`, P.fs, room);
+  const t1 = clip(`${refusedWord(l.outcome)}${head}${badge}`, P.fs, room);
   g += T(lx, cy + 4, t1, { size: P.fs, fill: color, weight: 600 });
   let after = width(t1, P.fs, true) + 8;
   const ticks = ticksOf(l);
@@ -621,7 +640,7 @@ function leaf(l, x, y, P, out) {
     yy += P.row * 0.95;
     const bx = lx + 6;
     const extra = l.base.effects.filter(e => !(P.paths.get(l.id) || []).some(h => h.op === e.op && h.tables.join() === e.tables.join())).map(stationLabel);
-    const btxt = clip(`base: ${l.base.outcome.kind === 'refused' ? 'refused ' : ''}${outcomeLabel(l.base.outcome)}${extra.length ? ` after ${extra.join(', ')}` : ''}`, P.fsS, room - 14);
+    const btxt = clip(`base: ${refusedWord(l.base.outcome)}${outcomeLabel(l.base.outcome)}${extra.length ? ` after ${extra.join(', ')}` : ''}`, P.fsS, room - 14);
     g += `<g data-f="${encodeURIComponent(`base:${l.id}`)}">${title('the same leaf at the base, where it was red')}${outcomeMark(bx, yy - 3, 'red', l.base.outcome.kind === 'refused', s * 0.8, true)}${T(bx + 11, yy, btxt, { size: P.fsS, fill: RED, opacity: 0.6 })}</g>`;
   }
   const what = `${l.id}: ${l.outcome.shown}${claimsText ? ` · ${claimsText}` : ''}`;
@@ -658,10 +677,10 @@ function witnessList(record, entry, subject, P, x0, y, out) {
 }
 
 // The author's text the engine could not check, outside the frame.
-export function renderNotes(record) {
-  const items = [];
-  for (const n of record.notes) items.push(`<li><span class="wh-note-kind">not a claim</span> <q>${esc(n.text)}</q> <span class="wh-note-at">${esc(n.at)}</span></li>`);
-  for (const r of record.refused) items.push(`<li><span class="wh-note-kind">refused</span> <q>${esc(r.words)}</q> names <code>${esc(r.id)}</code>, which the engine did not compute</li>`);
+export function renderNotes(record, entry) {
+  const items = [], about = x => x.entry === entry;
+  for (const n of record.notes.filter(about)) items.push(`<li><span class="wh-note-kind">not a claim</span> <q>${esc(n.text)}</q> <span class="wh-note-at">${esc(n.at)}</span></li>`);
+  for (const r of record.refused.filter(about)) items.push(`<li><span class="wh-note-kind">refused</span> <q>${esc(r.words)}</q> names <code>${esc(r.id)}</code>, which the engine did not compute</li>`);
   for (const m of record.mismatches) items.push(`<li><span class="wh-note-kind">mismatch</span> a scenario names <code>${esc(m.entry)}</code>, which is not an entry of this program</li>`);
   if (!items.length) return '';
   return `<aside class="wh-notes" aria-label="Unverified notes"><h3>Unverified notes from the author</h3><p>Outside the frame: text that is not a checkable claim, and names for ids the engine did not compute. Nothing here is checked or drawn.</p><ul>${items.join('')}</ul></aside>`;
@@ -686,7 +705,6 @@ export function mount(root, record) {
   const drawing = document.createElement('div');
   drawing.className = 'system-map-drawing';
   const notes = document.createElement('div');
-  notes.innerHTML = renderNotes(record);
   root.replaceChildren(crumb, toggle, drawing, notes);
   let w = 0;
   const draw = () => {
@@ -712,6 +730,7 @@ export function mount(root, record) {
     toggle.setAttribute('aria-pressed', String(cross === 'shown'));
     toggle.textContent = cross === 'folded' ? `Show the ${steps} wrapper and platform step${steps === 1 ? '' : 's'} inline` : 'Fold the wrapper and platform steps';
     drawing.innerHTML = renderWhatHappens(record, { width: w, entry, open, cross, ghosts });
+    notes.innerHTML = renderNotes(record, entry);
   };
   const choose = target => {
     const g = target.closest('[data-open]');

package/dist/studio-reference/balance-listed-laws.bosatsu

@@ -0,0 +1,29 @@
+package Example/BalanceListedLaws
+
+from Example/Balance import opening_balance
+from Yichus/Law import Domain, Law, Obligation, FiniteObligation, Witness
+
+export (never_negative,)
+exposes (Yichus/Law)
+
+# The person's rule, "a balance never goes below zero", checked only on
+# the deposits listed here. Every one passes, yet a deposit of -1 breaks
+# the rule: a listed check is bounded, never a proof for every input.
+
+def show(deposit: Int) -> String: int_to_String(deposit)
+
+def stays_above_zero(deposit: Int) -> Bool:
+  match cmp_Int(opening_balance(deposit), 0):
+    case LT: False
+    case _: True
+
+def empty_account(deposit: Int) -> Bool:
+  match deposit:
+    case 0: True
+    case _: False
+
+never_negative = FiniteObligation(
+  Obligation(Law("a balance never goes below zero", Domain("a first deposit", show, None, None), stays_above_zero),
+    [Witness("an account opened with nothing", empty_account)]),
+  [0, 5, 10]
+)

package/dist/studio-reference/balance.bosatsu

@@ -0,0 +1,7 @@
+package Example/Balance
+
+export (opening_balance,)
+
+# A new account opens with the first deposit as its balance. Nothing stops
+# a negative deposit, so a balance can go below zero.
+def opening_balance(deposit: Int) -> Int: deposit

package/dist/studio-reference/calculator.md

@@ -0,0 +1,20 @@
+# A calculation with no server
+
+The studio gives you this file when the program has no actions people call and keeps no records: a calculator, a quote, a planning tool. Such a program needs no server, no database and no sign-in, so the studio asks the person nothing about where it runs, who may see records or what happens when two people act at once.
+
+## What the studio still does for it
+
+- Every rule the person states about the numbers is a law the studio runs after each change: "more debt never raises what they can borrow", "the payment is never negative". Write each one (`yichus_reference` topic `laws`) and record it with `yichus_rules`. A law checked over every input is proven; one checked on sample inputs is bounded, and the page says which.
+- The page shows the shape of the program in the person's words.
+
+## Putting it on a page
+
+Yichus's calculator path turns the calculation into a page with sliders, results, charts and a Why button beside every number. Why shows the formula, the values that went into it and the source line it came from. The path runs in the person's browser, through a separate connection to the agent (`@yichus/mcp`, set up from the QuickStart at https://yich.us/start/quickstart.html, with the calculator walkthrough at https://yich.us/start/calculator.html). Keep the same calculation file: the laws the studio checked stay true of the page's numbers.
+
+Tell the person, in product terms:
+
+- The result is one page they can host anywhere and link to. Yichus does not document embedding it inside a site builder such as Squarespace or Wix.
+- The saved page carries its own scripts and styles, so it keeps working wherever it is hosted, whatever happens to yich.us. It leaves out the formula editor the workspace has.
+- Why explains what was calculated, not whether the model's assumptions suit their situation.
+
+If the person needs their own branded page instead, build it the usual way around the same pure calculation, and say plainly that the Why buttons then are not there.

package/dist/studio-reference/consent-laws.bosatsu

@@ -0,0 +1,37 @@
+package Example/ConsentLaws
+
+from Example/Consent import Consent, OptedIn, OptedOut, merge_consent
+from Yichus/Law import Domain, Law, Obligation, Witness
+
+export (opt_out_is_sticky,)
+exposes (Example/Consent, Yichus/Law)
+
+# The person's rule: "a fan who opts out stays opted out". The input is
+# what the fan said before (nothing yet, in or out) and a new sign-up.
+
+def said(choice: Consent) -> String:
+  match choice:
+    case OptedIn: "opted in"
+    case OptedOut: "opted out"
+
+def show(input: (Option[Consent], Consent)) -> String:
+  (before, signup) = input
+  earlier = match before:
+    case Some(choice): said(choice)
+    case None: "new"
+  concat_String([earlier, ", then signs up ", said(signup)])
+
+def stays_out(input: (Option[Consent], Consent)) -> Bool:
+  (before, signup) = input
+  match before:
+    case Some(OptedOut): merge_consent(before, signup) matches OptedOut
+    case _: True
+
+def had_opted_out(input: (Option[Consent], Consent)) -> Bool:
+  (before, _) = input
+  before matches Some(OptedOut)
+
+opt_out_is_sticky = Obligation(
+  Law("a fan who opted out stays opted out", Domain("an earlier choice and a new sign-up", show, None, None), stays_out),
+  [Witness("a fan who had opted out signs up again", had_opted_out)]
+)

package/dist/studio-reference/consent.bosatsu

@@ -0,0 +1,15 @@
+package Example/Consent
+
+export (Consent(), merge_consent)
+
+# What a fan said last about texts from an artist.
+enum Consent:
+  OptedIn
+  OptedOut
+
+# A fan who signs up again keeps an opt-out: only the fan's own "start"
+# can undo it, never a form.
+def merge_consent(before: Option[Consent], signup: Consent) -> Consent:
+  match before:
+    case Some(OptedOut): OptedOut
+    case _: signup

package/dist/studio-reference/deploy-platforms.md

@@ -1,16 +1,16 @@
-# Where the app runs: what to build for each platform
+# Where the app runs: how to put it online on each platform
 
-The studio gives you this file when the person has said where their app will run. It tells you what to build for that platform. Tell the person about the choices in product terms, such as "your app's server", "its database" or "the page people open". Never mention the programming language, file names or tool names.
+The studio gives you this file when the person has said where their app will run. The program is the same on every platform. This file says how to put it online on each one: which pieces run where, the database, and how background work starts. Tell the person about the choices in product terms, such as "your app's server", "its database" or "the page people open". Never name the programming language, and never mention file names or tool names.
 
 ## What every platform has to provide
 
 `api_deploy` produces one JavaScript module, the API engine. You don't write a server of your own. The engine needs four things:
 
 - **A Node.js process that keeps running.** `startYichusApiEngine(port)` listens on `PORT` and answers every route as a POST of JSON. It also serves `GET /health`, `GET /openapi.json` and the MCP endpoint at `/mcp`. The process holds state between requests (the idempotency cache, the JWKS cache), so it has to be a server process. A platform that starts a fresh function for each request is not enough.
-- **A PostgreSQL database.** The default store, `YICHUS_STORE=memory`, loses everything on restart. In production, use `@yichus/postgres-store` through `YICHUS_STORE=adapter:<module>`. The module reads `DATABASE_URL` and a namespace from the environment, and the start script runs `migrateYichusPostgres` first. `mathstreams/deploy/store.mjs` and `mathstreams/deploy/server.mjs` in the Yichus repository show both parts. Transactions run at SERIALIZABLE isolation and retry a bounded number of times.
+- **A PostgreSQL database.** The default store, `YICHUS_STORE=memory`, loses everything on restart. In production, use `@yichus/postgres-store` through `YICHUS_STORE=adapter:<module>`. The module reads `DATABASE_URL` and a namespace from the environment, and the start script runs `migrateYichusPostgres` first. `store.mjs` and `server.mjs`, which come with this file, are both parts, ready to copy. Transactions run at SERIALIZABLE isolation and retry a bounded number of times. The database can be one the person already has, such as their Supabase project's PostgreSQL: the store keeps its rows in a schema of its own (`yichus_runtime`), apart from the old tables, and its migration needs a role that may create that schema.
 - **An identity mode.** The engine refuses to listen without `YICHUS_AUTH`:
   - `jwt` takes `YICHUS_JWKS_URL` from any provider that publishes a JWKS, such as Auth0, Clerk, Amazon Cognito, Google Identity Platform or Firebase Auth, or Microsoft Entra ID.
-    An app that already signs people in with Supabase Auth keeps it: set `YICHUS_JWT_PROFILE=supabase-session`, `YICHUS_JWT_ISSUER=https://<project>.supabase.co/auth/v1` and `YICHUS_JWKS_URL` to that issuer plus `/.well-known/jwks.json`. The project must sign with asymmetric keys (RS256 or ES256), not its legacy shared secret.
+    An app that already signs people in with Supabase Auth keeps it: set `YICHUS_JWT_PROFILE=supabase-session`, `YICHUS_JWT_ISSUER=https://<project>.supabase.co/auth/v1` and `YICHUS_JWKS_URL` to that issuer plus `/.well-known/jwks.json`. A project still on its legacy JWT secret (HS256) sets `YICHUS_JWT_SECRET` to that secret as well as, or instead of, `YICHUS_JWKS_URL`; ask the person which their project uses (Supabase's JWT settings show it), and keep the secret in the engine host's environment only.
   - `clerk-api-key` is for API keys.
   - `proxy-header` is only for running behind a proxy you control that sets the caller's id.
   - `dev` is never used in production.
@@ -28,7 +28,7 @@ Render runs the whole app in one place, and it is the simplest choice.
 - **Database:** Render Postgres. Connect it to the service's `DATABASE_URL` with `fromDatabase`.
 - **Page people open:** a Static Site in the same Blueprint, or the API alone if the person's users are other programs.
 - **Background work:** a Cron Job or a Background Worker that calls the advance route.
-- **Config:** one `render.yaml` Blueprint holds all of these. `web/quickstart-app/render.yaml` and `mathstreams/deploy/render.yaml` are working examples. Keep secrets (the auth keys and model keys) as `sync: false` environment variables set in the dashboard.
+- **Config:** one `render.yaml` Blueprint holds all of these. The `render.yaml` that comes with this file is a working start for the server and its database. Keep secrets (the auth keys and model keys) as `sync: false` environment variables set in the dashboard.
 
 ## Vercel
 
@@ -40,7 +40,7 @@ Vercel is the place for the page people open, not for the API engine. Vercel Fun
 
 - **Webhooks and public forms that save something:** a public route only reads, so a provider's webhook (Twilio, Stripe, Meta) or a sign-up form a stranger submits goes to a Vercel route handler first. It checks the provider's signature against the exact request bytes, or the form's bot check, and then calls a `worker_route` on the engine with a worker secret (`yichusSecretWorkerVerifier`, kept in both hosts' environments). The engine's rules still decide what is saved.
 
-Tell the person their app lives in two places, the page on Vercel and the server elsewhere, and why.
+Tell the person their app lives in two places, the page on Vercel and the server elsewhere, and why. The second place is a second account and a second monthly bill; the studio asks them where it goes.
 
 ## Netlify
 

package/dist/studio-reference/laws.md

@@ -0,0 +1,62 @@
+# Rules the person states, written as laws
+
+When the person says what their app must always or never do ("a fan who opts out stays opted out", "a balance never goes below zero"), write the rule as a law in a `.bosatsu` file of the app. The studio runs every law on each `yichus_next`. A law that fails keeps the app from being done, and the page shows each rule with its status.
+
+The two files that come with this topic are a complete example: `consent.bosatsu` holds the rule the app follows, and `consent-laws.bosatsu` holds the law that checks it.
+
+## Writing a law
+
+Put the decision in a pure function, then state the rule about that function:
+
+```
+opt_out_is_sticky = Obligation(
+  Law("a fan who opted out stays opted out", Domain("an earlier choice and a new sign-up", show, None, None), stays_out),
+  [Witness("a fan who had opted out signs up again", had_opted_out)]
+)
+```
+
+- `Law(name, domain, check)`: `check` takes one input and is `True` when the rule holds for it. Pack several values into a tuple, as the example does.
+- `Domain(name, show, gen, shrink)`: `show` turns an input into text for a counterexample. With `gen` and `shrink` set to `None`, inputs come from the input's type.
+- `Witness(name, check)`: an input the rule is about must occur among the inputs checked. Without one, a law that holds because nothing ever happens would look like it holds. Name every case the rule is about.
+- Export the obligation, and list the packages its type mentions in `exposes`: `exposes (Example/Consent, Yichus/Law)`.
+- `FiniteObligation(obligation, [values])` checks exactly the listed inputs and nothing else. A pass covers only those inputs, so the rule shows as holding where checked, never as proven. Use it when the inputs that matter can truly be listed. `balance.bosatsu` and `balance-listed-laws.bosatsu`, which come with this topic, show one: the law passes on each listed deposit, while a deposit of -1 breaks the rule.
+
+Import `Domain`, `Law`, `Obligation`, `Witness` and `FiniteObligation` from `Yichus/Law`.
+
+State the person's rule, never what the code does. When a law fails, change the code. Never loosen the law.
+
+## How the studio checks it
+
+Each law is checked in two ways:
+
+- **Every input**, when the input's type has finitely many values (`Bool`, enums, `Option` and tuples of them). A pass here covers every value of the type, and the rule shows as proven.
+- **The listed inputs**, when the law is a `FiniteObligation`. A pass covers only the listed values, and the rule shows as holding where checked, not proven.
+- **200 generated inputs**, for types such as `Int` and `String`. A pass here is a bounded observation, not a proof, and the page says so.
+
+When a law cannot be decided (for example, a fold it cannot finish over every input), the rule shows as not decided. Simplify the function the law calls, give it an input type with finitely many values, or list the inputs that matter with `FiniteObligation` (a bounded check, as above).
+
+Once the laws are written, record each rule with the laws that check it: `yichus_rules` with `{"rules": [{"rule": "a fan who opts out stays opted out", "laws": ["opt_out_is_sticky"]}]}`. A law is named by its binding (`opt_out_is_sticky`) or by the name in its `Law`.
+
+A rule about what a page shows, or about something outside the app, can't be a law. Tell the person it is not checked, and leave it out.
+
+## Standard functions
+
+Every package can use these without an import (`Bosatsu/Predef`). There is no `trim`, lower-casing, `any` or `filter` here. The libraries below have some of those. Write the rest from `uncons_String`, `partition_String` and the folds.
+
+- **Booleans:** `and`, `or`, `not`, `xor`, `implies`, `eq_Bool`, `cmp_Bool`. These are functions, never infix words: write `a.and(b)` or `and(a, b)`, not `a and b`.
+- **Whole numbers (`Int`):** `add`, `sub`, `mul`, `div`, `div_mod`, `mod_Int`, `gcd_Int`, `eq_Int`, `cmp_Int`, `shift_left_Int`, `shift_right_Int`, `and_Int`, `or_Int`, `xor_Int`, `not_Int`, `popcount_Int`, `int_to_String`, `string_to_Int`, `int_to_Char`, `range`
+- **Decimals (`Float64`):** `addf`, `subf`, `mulf`, `divf`, `eq_Float64`, `cmp_Float64`
+- **Text (`String`, `Char`):** `concat_String`, `length_String`, `eq_String`, `cmp_String`, `string_Order`, `partition_String`, `rpartition_String`, `uncons_String`, `tail_or_empty_String`, `char_to_String`, `char_to_Int`, `char_List_to_String`, `eq_Char`, `cmp_Char`
+- **Lists:** `map_List`, `flat_map_List`, `foldl_List`, `foldr_List`, `length_List`, `reverse`, `reverse_concat`, `concat`, `replicate_List`, `build_List`
+- **Lookup tables (`Dict`):** `empty_Dict`, `add_key`, `get_key`, `remove_key`, `items`, `clear_Dict`
+- **Comparisons:** `eq_Comparison`, `cmp_Comparison`
+- **Debugging:** `trace`
+
+`foldl_List(list, start, fn)` takes its accumulator before the function: `foldl_List(items, 0, (total, item) -> total.add(item))`.
+
+These libraries come with every program, by import:
+
+- `Bosatsu/Char`: `string_to_Char_List`, `to_ascii_lower_case`, `to_ascii_upper_case`, `eq_ignore_ascii_case`, `is_ascii_whitespace`, `is_ascii_digit`, `is_ascii_alpha`, `to_digit` and more character tests.
+- `Yichus/Num/Float64`: `int_to_Float64`, `float64_to_Int`, `powf`, `minf`, `maxf`, and the operators `+.`, `-.`, `*.`, `/.`, for money and rates worked out in decimals. Its `Float64` is its own type, apart from the one above: import every decimal function and operator you use from it, and build constants with `int_to_Float64` or `divf` rather than writing decimal literals.
+- `Yichus/Law`: `exists_List`, `filter_List`, `size_List`, `contains_String`, besides the law types.
+- `Zafu/Control/IterState`: `foldl_List` with `done` and `continue`, for a scan that stops at the first match.

package/dist/studio-reference/porting.md

@@ -11,7 +11,7 @@ Before you write the new program, read the old app's code and find:
 - what happens when two people act on the same record at once,
 - what it does when a server or an outside service fails.
 
-Then build the new program so that it does the same, unless the person asks for something different. Move every rule into it, wherever the old app kept it (database policies and triggers, server routes, code in the pages): a rule left behind is one no check sees. The old pages can stay as the screens people use, calling the new program.
+Write the new program in a folder of its own, beside the old app rather than inside it: the studio reads every `.bosatsu` file in its folder. Then build the new program so that it does the same, unless the person asks for something different. Move every rule into it, wherever the old app kept it (database policies and triggers, server routes, code in the pages): a rule left behind is one no check sees. A rule the old app enforces, or the person states ("a fan who opts out stays opted out"), becomes a law the studio runs (reference topic `laws`). Records only the old app's server touched, such as which phone number belongs to whom or which webhook deliveries it has already seen, are the app's own: the person can choose "No person, only the app's own server" for them. The old pages can stay as the screens people use, calling the new program.
 
 ## Where the old app's entry points go
 
@@ -19,6 +19,8 @@ Public routes on the new program only read. Anything the old app saves from outs
 
 ## Bring the existing data over
 
+Before anything moves, list for the person every kind of record the old app keeps that the new program does not: timestamps such as first seen or consent time, a log of messages, raw payloads. Ask about each one: add it to the new program, or agree to leave it behind. A record dropped without their word is data lost.
+
 Write a one-off worker route that takes a batch of the old app's records and inserts them as the new program's typed rows in one transaction. Then write a script that posts the old database's export to it in batches. The imported rows pass the program's own types and rules, just like any other write, and a row the rules reject shows up as an error rather than as bad data. Map the old app's user ids to the ids the new sign-in gives the same people before you insert, or rows that belong to someone will not match the new program's ownership checks. Remove the route once the import is done and the person has checked the result.
 
 ## Use what you found in the conversation