yichus 0.3.2 → 0.3.4

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

@@ -41,7 +41,7 @@
 // (poteto) TLA+ diagrams.
 
 import { mark, tg, MIN_LABEL, COLORS as C } from './system-map.js';
-import { walk, leavesOf, pathEffects, allEffects, stationLabel, outcomeLabel, isWriteOp } from './what-happens-record.js';
+import { walk, leavesOf, pathEffects, allEffects, stationLabel, stationDetail, fromWord, 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';
@@ -223,9 +223,9 @@ export function renderWhatHappens(record, opts = {}) {
   y = frameTop + (phone ? 18 : 22);
   // the entry rack: the described entries, then one line for the others
   y = rack(record, entry, P, y, out, !!opts.ghosts || opts.open === 'ghosts');
-  // whether a base was compared, always in this place: a fix is then read
-  // off the frame, also when nothing is green
-  y = compared(record, P, y + (phone ? 13 : 15), out);
+  // what a compared base says, in this place: a fix is then read off the
+  // frame, also when nothing is green; with no base, nothing is drawn here
+  if (record.diff) y = compared(record, P, y + (phone ? 13 : 15), out);
   y += phone ? 10 : 14;
   // the entry's own line
   const o = parseOpen(opts.open);
@@ -243,6 +243,13 @@ export function renderWhatHappens(record, opts = {}) {
   }).map(effectKey));
   const x0 = P.pad + (phone ? 6 : 12);
   y = entryHead(entry, root || stepNode, record, P, x0, y, out, opts.open);
+  // entries that take the same steps, on other tables and checks
+  if (entry.sameShape && !root && !stepNode) {
+    const names = entry.sameShape.entries.map(id => id.replace(/^route:/, ''));
+    lines(`same steps as ${names.join(', ')} · on their own tables and checks`, P.fsS, P.W - P.pad - x0 - 12, false, 2)
+      .forEach(l => { out.push(tg([`sameShape:${entry.entry}`], T(x0 + 12, y + P.row * 0.2, l, { size: P.fsS, fill: C.muted, mono: false }))); y += P.row * 0.8; });
+    y += P.row * 0.3;
+  }
   const subject = root ? root.next : stepNode || entry.tree;
   // work beside the wrapper, folded; a wrapper's work after the handler is
   // folded on each path that runs it, just before its outcome
@@ -263,6 +270,35 @@ export function renderWhatHappens(record, opts = {}) {
     y = tree(subject, 0, x0, y, P, out, entry, true);
   }
   y = witnessList(record, entry, subject, P, x0, y + (phone ? 10 : 14), out);
+  // what each table it touches holds, by its checked row type, and then the tables only
+  // the entries with the same steps touch (which this tree stands for), each said to be theirs
+  const touched = new Map();
+  const touch = (es, by) => { for (const e of es || []) for (const tb of e.tables || []) if (!touched.has(tb)) touched.set(tb, by); };
+  for (const e of [entry, ...(entry.sameShape?.entries || []).map(id => record.entries.find(x => x.entry === id)).filter(Boolean)]) {
+    const by = e === entry ? null : e.entry.replace(/^route:/, '');
+    touch(e.effects, by);
+    walk(e === entry ? subject : e.tree, x => { if (!x.kind) touch(x.effects, by); });
+  }
+  for (const [tb, by] of [...touched].filter(([tb]) => record.rows && record.rows[tb])) {
+    for (const l of lines(`${by ? `in ${by}, ` : ''}${tb} holds ${record.rows[tb]}`, P.fsS, P.W - P.pad - x0 - 6, true, 3)) { y += P.row * 0.8; out.push(tg([`rows:${tb}`], T(x0, y, l, { size: P.fsS, fill: C.muted }))); }
+    y += P.row * 0.2;
+  }
+  // the checks it names are the author's labels: what each decides is in its code
+  const library = id => /^(Bosatsu|Yichus)\//.test(id);
+  const namedIds = [];
+  walk(subject, t => { if (t.kind === 'node' && t.from?.kind === 'call' && !library(t.from.callee) && !namedIds.includes(t.from.callee)) namedIds.push(t.from.callee); });
+  const named = [...new Set(namedIds.map(bare))];
+  if (named.length) {
+    const note = `${named.join(', ')}: names the author chose; this shows where each runs, what it is given and what happens when it fails, not what it decides`;
+    for (const l of lines(note, P.fsS, P.W - P.pad - x0 - 6, false, 3)) { y += P.row * 0.8; out.push(tg(['names'], T(x0, y, l, { size: P.fsS, fill: C.muted, mono: false }))); }
+    y += P.row * 0.3;
+  }
+  // what the author wrote above each named check: their words, in italic, not checked
+  for (const id of namedIds.filter(id => record.docs && record.docs[id])) {
+    const said = `${bare(id)}, in its author's comment (unchecked): ${record.docs[id].replace(/\s+/g, ' ')}`;
+    for (const l of lines(said, P.fsS, P.W - P.pad - x0 - 6, false, 3)) { y += P.row * 0.8; out.push(tg([`docs:${id}`], T(x0, y, l, { size: P.fsS, fill: C.muted, mono: false, italic: true }))); }
+    y += P.row * 0.2;
+  }
   const H = Math.ceil(y + (phone ? 10 : 16));
   const frame = labelled('frame', `<rect x="2.5" y="${frameTop}" width="${W - 5}" height="${H - frameTop - 3}" rx="10" fill="none" stroke="${C.frame}" stroke-width="1"/>` +
     `<text x="14" y="${frameTop + 4}" font-family="${SANS}" font-size="${phone ? 9 : 10}" font-weight="600" fill="${C.muted}" stroke="${C.page}" stroke-width="6" paint-order="stroke">Yichus output</text>`);
@@ -277,6 +313,12 @@ function rack(record, selected, P, y, out, expanded) {
   const x0 = pad + (phone ? 6 : 12);
   let x = x0, yy = y;
   const ghosts = record.entries.filter(e => !e.described);
+  // no entry described: one line that opens to list them all
+  if (ghosts.length === record.entries.length && !expanded) {
+    const n = ghosts.length, text = `${n} ${n === 1 ? 'entry' : 'entries'}`;
+    out.push(tg([`ghosts:${n}`], `<g data-ghosts="folded"${opener('ghosts', `Show the ${n} entries no scenario describes`)}>${title(`${n} entries no scenario describes`)}${ghostHead(x, yy)}${T(x + 11, yy, text, { size: fs, fill: C.muted, mono: false })}</g>`));
+    return yy + 4;
+  }
   out.push(T(x, yy, ghosts.length ? `entries · ${record.entries.length - ghosts.length} of ${record.entries.length} described by a scenario` : `entries · every one described`,
     { size: fs, fill: C.muted, mono: false }));
   yy += lh;
@@ -315,10 +357,6 @@ 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) {
-    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]];
   if (d.unresolved.length) parts.push([`${d.unresolved.length} no longer checked`, C.muted, 600]);
   if (d.goneAtHead.length) parts.push([`${d.goneAtHead.length} gone with ${d.goneAtHead.length === 1 ? 'its entry' : 'their entries'}`, C.muted, null]);
@@ -370,13 +408,25 @@ function stations(effects, x, y, P, out, key) {
     const text = stationLabel(e) + (isCore(e) ? '' : ` · ${e.phase === 'after' ? `after the handler${whose}${after ? (after.everyPath ? ' · on every path that runs it' : ' · not on every path that runs it') : ''}` : e.layer === 'beside' ? 'beside the wrapper' : `before the handler${whose}`}`);
     const where = `${text} in ${String(e.site).split('::').pop()}${e.line ? `, line ${e.line}` : ''}`;
     const rows = lines(text, P.fsS, P.W - P.pad - x - r - 10, true, 2);
-    out.push(tg([`effect:${key}:${e.op}:${e.tables.join(',')}`], `<g data-layer="${e.layer || 'core'}">${title(where)}${ring}${rows.map((l, i) => T(x + r + 6 + (i ? 8 : 0), cy + 3.5 + i * P.row * 0.8, l, { size: P.fsS, fill: isCore(e) ? color : C.hullInk })).join('')}</g>`));
-    if (rows.length > 1) out.push(line(x, cy, x, cy + P.row * 1.2));
-    y = cy + P.row * 0.6 + (rows.length - 1) * P.row * 0.8;
+    // the row it touches and where what it writes comes from, under the label
+    // (measured at the size it is drawn at: never below the smallest label)
+    const dsz = Math.max(MIN_LABEL, P.fsS - 1);
+    const detail = stationDetail(e), more = detail ? lines(detail, dsz, P.W - P.pad - x - r - 18, true, 2) : [];
+    const all = [...rows.map(l => [l, P.fsS, isCore(e) ? color : C.hullInk]), ...more.map(l => [l, dsz, C.muted])];
+    out.push(tg([`effect:${key}:${e.op}:${e.tables.join(',')}`], `<g data-layer="${e.layer || 'core'}">${title(detail ? `${where}: ${detail}` : where)}${ring}${all.map(([l, size, fill], i) => T(x + r + 6 + (i ? 8 : 0), cy + 3.5 + i * P.row * 0.8, l, { size, fill })).join('')}</g>`));
+    if (all.length > 1) out.push(line(x, cy, x, cy + P.row * (0.6 + (all.length - 1) * 0.8)));
+    y = cy + P.row * 0.6 + (all.length - 1) * P.row * 0.8;
   }
   return y;
 }
 
+const forkSources = t => {
+  const f = t.from || {};
+  if (f.kind === 'call' || f.kind === 'derived') return (f.sources || []).map(fromWord).join(', ') || null;
+  if (f.kind === 'read') return f.op === 'mint id' ? 'new id' : `${f.table || bare(f.primitive)} as read`;
+  if (f.kind === 'request' || f.kind === 'caller') return [f.kind, ...(f.path || [])].join('.');
+  return null;
+};
 // 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.
@@ -467,9 +517,18 @@ function tree(t, depth, x, y, P, out, entry, top) {
     out.push(tg([`words:${t.id}`], `<g>${title(`${t.test} (${t.key})`)}${T(lx, yy, clip(t.words, P.fs, room, false, 400, true), { size: P.fs, italic: true, mono: false, fill: crossNode ? C.hullInk : C.ink })}</g>`));
     if (!P.phone) out.push(T(lx + Math.min(room, width(clip(t.words, P.fs, room, false, 400, true), P.fs, false, 400, true)) + 8, yy, clip(t.test, P.fsS, Math.max(0, room - width(t.words, P.fs, false, 400, true) - 10)), { size: P.fsS, fill: C.faint }));
   } else {
-    for (const [i, l] of lines(t.test, P.fs, room, !guard, 2, guard ? 600 : 400).entries())
+    const rows = lines(t.test, P.fs, room, !guard, 2, guard ? 600 : 400);
+    for (const [i, l] of rows.entries())
       out.push(T(lx, yy + i * P.row * 0.85, l, { size: P.fs, mono: !guard, fill: guard ? RED : crossNode ? C.hullInk : C.ink2, weight: guard ? 600 : null }));
-    if (width(t.test, P.fs, !guard, guard ? 600 : 400) > room) yy += P.row * 0.85;
+    if (rows.length > 1) yy += P.row * 0.85;
+    // what the branch tests comes from: the request, the caller, a read
+    const src = forkSources(t);
+    if (src) {
+      const after = width(rows[rows.length - 1], P.fs, !guard, guard ? 600 : 400) + 8, left = room - after;
+      const text = `← ${src}`;
+      if (width(text, P.fsS, true) <= left) out.push(T(lx + after, yy, text, { size: P.fsS, fill: C.muted }));
+      else { yy += P.row * 0.8; out.push(T(lx, yy, clip(text, P.fsS, room), { size: P.fsS, fill: C.muted })); }
+    }
   }
   y = yy + P.row * 0.35;
   // the spine continues straight down: the arm that reaches the main

package/dist/studio-reference/calculator.md

@@ -5,6 +5,7 @@ The studio gives you this file when the program has no actions people call and k
 ## 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.
+- `api_suggest_properties` drafts a law for each answer the calculation offers: a floor every answer stays at or above, for the inputs the person means. Fill in the floor and which inputs are in use from the person's words; the draft checks inconclusive until then, never broken.
 - The page shows the shape of the program in the person's words.
 
 ## Putting it on a page

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

@@ -13,9 +13,12 @@ The studio gives you this file when the person has said where their app will run
     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.
+  - `public` is for an app where everyone may do everything and nobody signs in. The engine starts in this mode only when every action is open to everyone, and otherwise it names the ones that need to know the caller.
   - `dev` is never used in production.
 - **HTTPS in front.** Every platform below terminates TLS for you.
 
+An app that keeps no records and lets everyone use every action, such as a calculator served as an API, needs less than this. It needs no database, because the memory store has nothing to lose. It needs no identity provider either: run it with `YICHUS_AUTH=public`. It still needs a Node.js process and HTTPS. A calculator that only runs in the page people open needs no server at all (`yichus_reference` topic `calculator`).
+
 Where the person chose "one server", configure the platform so that exactly one copy runs. Each platform below says how. Several platforms add copies on their own when traffic grows, and then the one-server assumption is false. If the person can't accept that limit, go back and answer the topology question "several copies".
 
 Work that takes longer than one request, waits on an outside service, or must finish later should never be one long request. Write it as a portable step program (`yichus_reference` topic `portable-programs`). Then have a scheduled job or a worker call the route that advances it. Every platform below can run that job.

package/dist/studio-reference/mutants/double-signup.bosatsu

@@ -0,0 +1,149 @@
+package Example/Signups
+
+# A mutant of ../signups.bosatsu, kept so cases/signups-case.json is shown
+# to fail on it: the same app without the check that the volunteer already
+# holds a spot on the shift, so one volunteer takes two spots, and
+# cancelling removes both sign-ups but gives back only one spot.
+
+from Yichus/IO import IO, pure, flat_map
+from Yichus/Transaction import TxTable, Txn, stored_table, tx_bind, tx_pure, tx_read, tx_write, tx_abort, transaction, replied
+from Yichus/Access import Principal, AccessRule, AccessSpec, Public, OwnerScoped
+from Yichus/Data import Db, Table, table, db_read, db_query
+from Yichus/Service import Reply, Done, Refused, TryAgain, handler, route, service_def, ReadPerm, WritePerm, QueryPerm
+
+export (signups_api, access_rules, Shift(), Signup(), take_spot)
+exposes (Yichus/Access, Yichus/Service)
+
+struct Shift(title: String, starts_at: String, spots: Int, taken: Int)
+
+struct Signup(shift_id: String, volunteer_name: String)
+
+# The decision: a shift with `spots` places, `taken` already taken,
+# has room for one more only while taken is below spots.
+def has_room(spots: Int, taken: Int) -> Bool:
+  cmp_Int(taken, spots) matches LT
+
+# The shift after one more volunteer takes a spot, or None when full.
+def take_spot(shift: Shift) -> Option[Shift]:
+  Shift(title, starts_at, spots, taken) = shift
+  if has_room(spots, taken):
+    Some(Shift(title, starts_at, spots, taken.add(1)))
+  else:
+    None
+
+# The declared access surface. `api_verify` proves each rule against
+# the handlers below — and keeps proving it as this file is edited.
+access_rules = AccessSpec([
+  AccessRule("shifts", Public),
+  AccessRule("signups", OwnerScoped),
+])
+
+# Why a change was refused; the error body's code is its name in
+# snake_case. maybe_saved: the commit was not confirmed, so sending
+# the change again could repeat it. The others were refused before
+# anything was saved, and sending the same change again is refused again.
+enum ChangeRefused:
+  MaybeSaved
+  ShiftFull
+  NoSuchShift
+  AlreadySignedUp
+
+def unsaved[a](reason: ChangeRefused) -> Reply[ChangeRefused, a]:
+  match reason:
+    case ShiftFull: Refused("the shift is full", reason)
+    case NoSuchShift: Refused("there is no such shift", reason)
+    case AlreadySignedUp: Refused("the volunteer is already signed up for this shift", reason)
+    case MaybeSaved: Refused("the change may already be saved; list the signups before sending it again", reason)
+
+# Shifts are public: shared rows, no key discipline claimed.
+def shifts_table(db: Db) -> Table[Shift]:
+  table(db, "shifts")
+
+def get_shift(db: Db, id: String) -> IO[Shift]:
+  db_read(shifts_table(db), id)
+
+def list_shifts(db: Db) -> IO[List[Shift]]:
+  db_query(shifts_table(db))
+
+# Signups are owner-scoped: one row per user, keyed by exactly
+# Principal.user_id, holding that user's list. The analyzer proves no
+# handler can reach another caller's row.
+def signups_table(db: Db) -> Table[List[Signup]]:
+  table(db, "signups")
+
+# The same table inside a transaction. Every change to a caller's row
+# goes through one, so changes made at the same moment, on one server
+# or several, never lose one another.
+signups_rows: TxTable[s, List[Signup]] = stored_table("signups")
+
+def list_signups(db: Db, p: Principal) -> IO[List[Signup]]:
+  Principal(uid, _) = p
+  db_read(signups_table(db), uid)
+
+shifts_rows: TxTable[s, Shift] = stored_table("shifts")
+
+def add_signup_plan[s](uid: String, item: Signup) -> Txn[s, ChangeRefused, List[Signup]]:
+  Signup(shift_id, _) = item
+  found <- tx_bind(tx_read(signups_rows, uid))
+  saved = match found:
+    case Some(saved): saved
+    case None: []
+  shift_found <- tx_bind(tx_read(shifts_rows, shift_id))
+  match shift_found:
+    case None: tx_abort(NoSuchShift)
+    case Some(shift):
+      match take_spot(shift):
+        case None: tx_abort(ShiftFull)
+        case Some(updated):
+          _ <- tx_bind(tx_write(shifts_rows, shift_id, updated))
+          items = [item, *saved]
+          _ <- tx_bind(tx_write(signups_rows, uid, items))
+          tx_pure(items)
+
+def add_signup(db: Db, p: Principal, item: Signup) -> IO[Reply[ChangeRefused, List[Signup]]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> add_signup_plan(uid, item)))
+  pure(replied(outcome, Done, unsaved, Refused("the signup may already be saved; list the signups before adding it again", MaybeSaved)))
+
+def without(items: List[Signup], shift_id: String) -> List[Signup]:
+  items.foldr_List((item, kept) -> (
+    Signup(id, _) = item
+    kept if eq_String(id, shift_id) else [item, *kept]
+  ), [])
+
+def give_back(shift: Shift) -> Shift:
+  Shift(title, starts_at, spots, taken) = shift
+  Shift(title, starts_at, spots, taken.sub(1))
+
+def cancel_signup_plan[s](uid: String, shift_id: String) -> Txn[s, ChangeRefused, List[Signup]]:
+  found <- tx_bind(tx_read(signups_rows, uid))
+  items = match found:
+    case Some(saved): saved
+    case None: []
+  kept = without(items, shift_id)
+  if eq_Int(length_List(kept), length_List(items)):
+    tx_pure(items)
+  else:
+    shift_found <- tx_bind(tx_read(shifts_rows, shift_id))
+    match shift_found:
+      case None: tx_abort(NoSuchShift)
+      case Some(shift):
+        _ <- tx_bind(tx_write(shifts_rows, shift_id, give_back(shift)))
+        _ <- tx_bind(tx_write(signups_rows, uid, kept))
+        tx_pure(kept)
+
+def cancel_signup(db: Db, p: Principal, shift_id: String) -> IO[Reply[ChangeRefused, List[Signup]]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> cancel_signup_plan(uid, shift_id)))
+  pure(replied(outcome, Done, unsaved, TryAgain("the sign-up may not have been cancelled; send the request again")))
+
+signups_api = service_def(
+  "signups",
+  [
+    route("/shifts/get", handler("get_shift", get_shift), [ReadPerm("shifts")]),
+    route("/shifts", handler("list_shifts", list_shifts), [QueryPerm("shifts")]),
+    route("/signups", handler("list_signups", list_signups), [ReadPerm("signups")]),
+    route("/signups/add", handler("add_signup", add_signup), [ReadPerm("shifts"), WritePerm("shifts"), ReadPerm("signups"), WritePerm("signups")]),
+    route("/signups/cancel", handler("cancel_signup", cancel_signup), [ReadPerm("shifts"), WritePerm("shifts"), ReadPerm("signups"), WritePerm("signups")]),
+  ]
+)

package/dist/studio-reference/mutants/overfill.bosatsu

@@ -0,0 +1,153 @@
+package Example/Signups
+
+# A mutant of ../signups.bosatsu, kept so cases/signups-case.json is shown
+# to fail on it: sign-up takes a spot without asking take_spot whether one
+# is left, so a full shift takes one more volunteer.
+
+from Yichus/IO import IO, pure, flat_map
+from Yichus/Transaction import TxTable, Txn, stored_table, tx_bind, tx_pure, tx_read, tx_write, tx_abort, transaction, replied
+from Yichus/Access import Principal, AccessRule, AccessSpec, Public, OwnerScoped
+from Yichus/Data import Db, Table, table, db_read, db_query
+from Yichus/Service import Reply, Done, Refused, TryAgain, handler, route, service_def, ReadPerm, WritePerm, QueryPerm
+
+export (signups_api, access_rules, Shift(), Signup(), take_spot)
+exposes (Yichus/Access, Yichus/Service)
+
+struct Shift(title: String, starts_at: String, spots: Int, taken: Int)
+
+struct Signup(shift_id: String, volunteer_name: String)
+
+# The decision: a shift with `spots` places, `taken` already taken,
+# has room for one more only while taken is below spots.
+def has_room(spots: Int, taken: Int) -> Bool:
+  cmp_Int(taken, spots) matches LT
+
+# The shift after one more volunteer takes a spot, or None when full.
+def take_spot(shift: Shift) -> Option[Shift]:
+  Shift(title, starts_at, spots, taken) = shift
+  if has_room(spots, taken):
+    Some(Shift(title, starts_at, spots, taken.add(1)))
+  else:
+    None
+
+# The declared access surface. `api_verify` proves each rule against
+# the handlers below — and keeps proving it as this file is edited.
+access_rules = AccessSpec([
+  AccessRule("shifts", Public),
+  AccessRule("signups", OwnerScoped),
+])
+
+# Why a change was refused; the error body's code is its name in
+# snake_case. maybe_saved: the commit was not confirmed, so sending
+# the change again could repeat it. The others were refused before
+# anything was saved, and sending the same change again is refused again.
+enum ChangeRefused:
+  MaybeSaved
+  ShiftFull
+  NoSuchShift
+  AlreadySignedUp
+
+def unsaved[a](reason: ChangeRefused) -> Reply[ChangeRefused, a]:
+  match reason:
+    case ShiftFull: Refused("the shift is full", reason)
+    case NoSuchShift: Refused("there is no such shift", reason)
+    case AlreadySignedUp: Refused("the volunteer is already signed up for this shift", reason)
+    case MaybeSaved: Refused("the change may already be saved; list the signups before sending it again", reason)
+
+# Shifts are public: shared rows, no key discipline claimed.
+def shifts_table(db: Db) -> Table[Shift]:
+  table(db, "shifts")
+
+def get_shift(db: Db, id: String) -> IO[Shift]:
+  db_read(shifts_table(db), id)
+
+def list_shifts(db: Db) -> IO[List[Shift]]:
+  db_query(shifts_table(db))
+
+# Signups are owner-scoped: one row per user, keyed by exactly
+# Principal.user_id, holding that user's list. The analyzer proves no
+# handler can reach another caller's row.
+def signups_table(db: Db) -> Table[List[Signup]]:
+  table(db, "signups")
+
+# The same table inside a transaction. Every change to a caller's row
+# goes through one, so changes made at the same moment, on one server
+# or several, never lose one another.
+signups_rows: TxTable[s, List[Signup]] = stored_table("signups")
+
+def list_signups(db: Db, p: Principal) -> IO[List[Signup]]:
+  Principal(uid, _) = p
+  db_read(signups_table(db), uid)
+
+shifts_rows: TxTable[s, Shift] = stored_table("shifts")
+
+# A volunteer takes at most one spot on a shift.
+def signed_up(items: List[Signup], shift_id: String) -> Bool:
+  items.foldl_List(False, (seen, Signup(id, _)) -> seen.or(eq_String(id, shift_id)))
+
+def add_signup_plan[s](uid: String, item: Signup) -> Txn[s, ChangeRefused, List[Signup]]:
+  Signup(shift_id, _) = item
+  found <- tx_bind(tx_read(signups_rows, uid))
+  saved = match found:
+    case Some(saved): saved
+    case None: []
+  if signed_up(saved, shift_id):
+    tx_abort(AlreadySignedUp)
+  else:
+    shift_found <- tx_bind(tx_read(shifts_rows, shift_id))
+    match shift_found:
+      case None: tx_abort(NoSuchShift)
+      case Some(shift):
+        Shift(title, starts_at, spots, taken) = shift
+        _ <- tx_bind(tx_write(shifts_rows, shift_id, Shift(title, starts_at, spots, taken.add(1))))
+        items = [item, *saved]
+        _ <- tx_bind(tx_write(signups_rows, uid, items))
+        tx_pure(items)
+
+def add_signup(db: Db, p: Principal, item: Signup) -> IO[Reply[ChangeRefused, List[Signup]]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> add_signup_plan(uid, item)))
+  pure(replied(outcome, Done, unsaved, Refused("the signup may already be saved; list the signups before adding it again", MaybeSaved)))
+
+def without(items: List[Signup], shift_id: String) -> List[Signup]:
+  items.foldr_List((item, kept) -> (
+    Signup(id, _) = item
+    kept if eq_String(id, shift_id) else [item, *kept]
+  ), [])
+
+def give_back(shift: Shift) -> Shift:
+  Shift(title, starts_at, spots, taken) = shift
+  Shift(title, starts_at, spots, taken.sub(1))
+
+def cancel_signup_plan[s](uid: String, shift_id: String) -> Txn[s, ChangeRefused, List[Signup]]:
+  found <- tx_bind(tx_read(signups_rows, uid))
+  items = match found:
+    case Some(saved): saved
+    case None: []
+  kept = without(items, shift_id)
+  if eq_Int(length_List(kept), length_List(items)):
+    tx_pure(items)
+  else:
+    shift_found <- tx_bind(tx_read(shifts_rows, shift_id))
+    match shift_found:
+      case None: tx_abort(NoSuchShift)
+      case Some(shift):
+        _ <- tx_bind(tx_write(shifts_rows, shift_id, give_back(shift)))
+        _ <- tx_bind(tx_write(signups_rows, uid, kept))
+        tx_pure(kept)
+
+def cancel_signup(db: Db, p: Principal, shift_id: String) -> IO[Reply[ChangeRefused, List[Signup]]]:
+  Principal(uid, _) = p
+  outcome <- flat_map(transaction(db, _ -> cancel_signup_plan(uid, shift_id)))
+  pure(replied(outcome, Done, unsaved, TryAgain("the sign-up may not have been cancelled; send the request again")))
+
+signups_api = service_def(
+  "signups",
+  [
+    route("/shifts/get", handler("get_shift", get_shift), [ReadPerm("shifts")]),
+    route("/shifts", handler("list_shifts", list_shifts), [QueryPerm("shifts")]),
+    route("/signups", handler("list_signups", list_signups), [ReadPerm("signups")]),
+    route("/signups/add", handler("add_signup", add_signup), [ReadPerm("shifts"), WritePerm("shifts"), ReadPerm("signups"), WritePerm("signups")]),
+    route("/signups/cancel", handler("cancel_signup", cancel_signup), [ReadPerm("shifts"), WritePerm("shifts"), ReadPerm("signups"), WritePerm("signups")]),
+  ]
+)

package/dist/studio-reference/near-miss-case.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": "protocol-case-1.0",
+  "name": "Every action that changes sign-ups keeps the shift count",
+  "assumptions": [
+    "serializable-atomic-transactions",
+    "rollback-on-abort-and-retry-exhaustion",
+    "commit-unknown-may-commit",
+    "stable-time-within-attempt",
+    "no-unmodeled-writers",
+    "preauthenticated-principals"
+  ],
+  "initialRows": {
+    "shifts": {
+      "s1": {
+        "title": "Sorting",
+        "starts_at": "9am",
+        "spots": 1,
+        "taken": 0
+      }
+    },
+    "signups": {}
+  },
+  "initialize": [],
+  "requests": [
+    {
+      "instance": "a",
+      "delivery": "a",
+      "call": {
+        "binding": "Example/Signups::add_signup",
+        "arguments": {
+          "p": {
+            "user_id": "ann",
+            "roles": []
+          },
+          "item": {
+            "shift_id": "s1",
+            "volunteer_name": "Ann"
+          }
+        }
+      }
+    },
+    {
+      "instance": "b",
+      "delivery": "b",
+      "call": {
+        "binding": "Example/Signups::put_signups",
+        "arguments": {
+          "p": {
+            "user_id": "bo",
+            "roles": []
+          },
+          "items": [
+            {
+              "shift_id": "s1",
+              "volunteer_name": "Bo"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "instance": "c",
+      "delivery": "c",
+      "call": {
+        "binding": "Example/Signups::clear_signups",
+        "arguments": {
+          "p": {
+            "user_id": "ann",
+            "roles": []
+          }
+        }
+      }
+    }
+  ],
+  "times": [
+    1000
+  ],
+  "externalResults": {},
+  "invariants": [
+    {
+      "name": "spots-match-signups",
+      "binding": "Example/SignupsCase::spots_match_signups",
+      "arguments": {
+        "after": "after"
+      },
+      "when": "always"
+    }
+  ],
+  "traceInvariants": [],
+  "witnesses": [
+    {
+      "name": "someone-signed-up",
+      "kind": "table-nonempty",
+      "table": "signups"
+    }
+  ],
+  "bounds": {
+    "maxStates": 100000,
+    "maxDepth": 30,
+    "maxOperations": 60,
+    "maxFaults": 0,
+    "maxCrashes": 0
+  }
+}