yichus 0.3.3 → 0.3.4

package/dist/main.js

@@ -829,6 +829,10 @@ var WHAT = {
 };
 var PACKAGE = "a section of the program";
 var DEFINITION = "a piece of the program";
+var MADE = "a kind of value the program works out";
+var OFFERED = "a part the program offers for others to use";
+var DEFINED = { makes: MADE, exports: OFFERED, exported: OFFERED };
+var PACKAGE_KEYS = /* @__PURE__ */ new Set(["package", "pkg", "instantiatingPackages"]);
 var VALUE = "a kind of value";
 var TYPES = /* @__PURE__ */ new Set(["type", "types", "signature"]);
 var WORD = /[A-Za-z_][\w/]*::\w+|[A-Za-z_]\w*/g;
@@ -856,15 +860,17 @@ var leaves = (record, visit) => {
 function nameableParts(map, own) {
   const found = /* @__PURE__ */ new Map();
   const theirs2 = (pkg) => !own || own.has(pkg);
+  const rank = (what) => [OFFERED, MADE, PACKAGE].indexOf(what);
   const add = (code, what) => {
-    if (code && !found.has(code) && !(code in PREDEF_WORDS) && (what !== PACKAGE || theirs2(code))) found.set(code, what);
+    if (code && (!found.has(code) || rank(what) > rank(found.get(code))) && !(code in PREDEF_WORDS) && (what !== PACKAGE || theirs2(code))) found.set(code, what);
   };
-  const idParts = (id) => {
+  const idParts = (id, key) => {
     const i = id.lastIndexOf("::");
     if (!theirs2(id.slice(0, i))) return;
     add(id.slice(0, i), PACKAGE);
-    add(id.slice(i + 2), DEFINITION);
+    add(id.slice(i + 2), DEFINED[key] ?? DEFINITION);
   };
+  const isPackage = (s, key) => own?.has(s) || PACKAGE_KEYS.has(key) || s.includes("/");
   leaves(map, (s, key) => {
     if (key === "guardIds" && s.startsWith("route:")) return;
     if (s.startsWith("route:")) return add(s.slice(6), WHAT.path);
@@ -874,12 +880,12 @@ function nameableParts(map, own) {
       return;
     }
     if (s.includes("::")) {
-      for (const w of s.match(WORD)) if (w.includes("::")) idParts(w);
+      for (const w of s.match(WORD)) if (w.includes("::")) idParts(w, key);
       return;
     }
     if (STRUCTURAL.has(key)) return;
-    if (key === "name" || key === "package" || key === "pkg" || key === "instantiatingPackages" || key === "cycles" || key === "to") return add(s, s.includes("/") ? PACKAGE : DEFINITION);
-    add(s, WHAT[key] ?? DEFINITION);
+    if (key === "name" || PACKAGE_KEYS.has(key) || key === "cycles" || key === "to" || own?.has(s)) return add(s, isPackage(s, key) ? PACKAGE : DEFINITION);
+    add(s, WHAT[key] ?? DEFINED[key] ?? DEFINITION);
   });
   for (const b of map.bundles ?? []) if (b.count > 1) found.delete(b.label);
   return [...found].map(([code, what]) => ({ code, what })).sort((a, b) => a.code.localeCompare(b.code));
@@ -1259,6 +1265,7 @@ var Step = z3.looseObject({ op: z3.string(), tables: z3.array(z3.string()).defau
 var Route = z3.looseObject({
   path: z3.string(),
   handler: z3.string(),
+  handlerBinding: z3.string(),
   authority: z3.string().optional(),
   tables: z3.array(z3.string()).default([]),
   inferredSteps: z3.array(Step).default([])
@@ -1277,8 +1284,10 @@ var Table = z3.looseObject({
 });
 var Report = z3.looseObject({
   surface: z3.looseObject({ routes: z3.array(Route).default([]) }).default({ routes: [] }),
-  dataModel: z3.looseObject({ tables: z3.array(Table).default([]) }).default({ tables: [] })
+  dataModel: z3.looseObject({ tables: z3.array(Table).default([]) }).default({ tables: [] }),
+  shape: z3.looseObject({ packages: z3.array(z3.looseObject({ name: z3.string() })).default([]) }).default({ packages: [] })
 });
+var handlerOf = (report, route) => route.handlerBinding.includes("::") ? route.handlerBinding : `${report.shape.packages[0]?.name}::${route.handlerBinding}`;
 var Entry = z3.looseObject({ entry: z3.string(), resources: z3.array(z3.string()).default([]) });
 var Structure = z3.looseObject({ entries: z3.array(Entry).default([]) });
 var ACCESS_RULES = {
@@ -1359,11 +1368,36 @@ function accessQuestion(table, names) {
     ask: `Your app saves "${shown(names, table.name)}"${table.name in names ? "" : " records"}. Who should be able to see one, and who should be able to change it?`,
     why: "Without a rule the app has no way to know a record is private. Yichus checks every place the app reads or changes these records against the rule you choose.",
     choices: [
-      { id: "owner", label: "Only the person who created it", means: "Every read and write is tied to the signed-in person, and the check proves no one reaches another person's records. No one else, not even a manager, sees or changes them, so anything someone else decides about them, such as an approval, belongs in records only the person who decides it may change." },
-      { id: "shared", label: "Only the people a rule lets in", means: "For example the members of a team, or the people a record was shared with. Every read and change goes through that rule, except work done under a role you name, such as an administrator or the app's own server, and the check proves nothing else skips it." },
-      { id: "server-only", label: "No person, only the app's own server", means: "Records the app keeps for itself, such as which number belongs to whom or which messages it has already seen. Only work the app's own server starts may read or change them, and the check proves nothing a person calls reaches them." },
-      { id: "everyone-reads", label: "Everyone can see it; only certain roles can change it", means: "Anyone can read; changes need a role the app gives out." },
-      { id: "public", label: "Anyone, even without signing in", means: "Nothing in these records is private." }
+      {
+        id: "owner",
+        label: "Only the person who created it",
+        means: "Every read and write is tied to the signed-in person, and the check proves no one reaches another person's records. No one else, not even a manager, sees or changes them, so anything someone else decides about them, such as an approval, belongs in records only the person who decides it may change.",
+        unchecked: "Decisions someone else should make about these records, such as an approval: the person who creates one can change all of it."
+      },
+      {
+        id: "shared",
+        label: "Only the people a rule lets in",
+        means: "For example the members of a team, or the people a record was shared with. Every read and change goes through that rule, except work done under a role you name, such as an administrator or the app's own server, and the check proves nothing else skips it.",
+        unchecked: "Whether the rule lets in the right people. The check proves every read and change goes through it; who it lets in is what your agent wrote."
+      },
+      {
+        id: "server-only",
+        label: "No person, only the app's own server",
+        means: "Records the app keeps for itself, such as which number belongs to whom or which messages it has already seen. Only work the app's own server starts may read or change them, and the check proves nothing a person calls reaches them.",
+        unchecked: "What the app's own server does with these records."
+      },
+      {
+        id: "everyone-reads",
+        label: "Everyone can see it; only certain roles can change it",
+        means: "Anyone can read; changes need a role the app gives out.",
+        unchecked: "Who is given the role: that is up to sign-in."
+      },
+      {
+        id: "public",
+        label: "Anyone, even without signing in",
+        means: "Nothing in these records is private.",
+        unchecked: "Nothing protects these records: anyone, even without signing in, can read, change and delete every one."
+      }
     ],
     fact: `The program stores rows in "${table.name}" (policy declared: ${table.policy ?? "none"}).`
   };
@@ -1377,8 +1411,18 @@ function togetherQuestion(table, handlers, names) {
     ask: `Two requests change the same record in "${shown(names, table.name)}" at the same moment (${who}). What should happen?`,
     why: "When a request reads a record and then writes it back, a second request in between can be silently lost, or both can pass a limit only one should, such as two people taking the last spot. People rarely notice until data goes missing.",
     choices: [
-      { id: "keep-both", label: "Both changes are kept", means: "Each change happens as one indivisible step that sees the one before it, so neither can overwrite the other unseen and a limit the app checks is never passed twice; the check proves no change is lost." },
-      { id: "refuse-second", label: "The second is refused and they try again", means: "A change made to an out-of-date copy is turned away; the check proves no change is lost." }
+      {
+        id: "keep-both",
+        label: "Both changes are kept",
+        means: "Each change happens as one indivisible step that sees the one before it, so neither can overwrite the other unseen and a limit the app checks is never passed twice; the check proves no change is lost.",
+        unchecked: "A limit counted across many records, such as sign-ups against the spots on a shift. A rule you give can check that, with a scenario that runs every action that changes the records the rule is about."
+      },
+      {
+        id: "refuse-second",
+        label: "The second is refused and they try again",
+        means: "A change made to an out-of-date copy is turned away; the check proves no change is lost.",
+        unchecked: "A limit counted across many records, such as sign-ups against the spots on a shift. A rule you give can check that, with a scenario that runs every action that changes the records the rule is about."
+      }
     ],
     fact: `${handlers.join(", ")} ${handlers.length === 1 ? "reads" : "read"} "${table.name}" and then ${handlers.length === 1 ? "writes" : "write"} it.`
   };
@@ -1391,7 +1435,12 @@ function partialQuestion(route, tables, names) {
     ask: `If the server stops halfway through "${shown(names, route.path)}" (a crash, a database error, a timeout), may part of its changes stay saved?`,
     why: `This action changes ${tables.map((t) => `"${shown(names, t)}"`).join(" and ")} in more than one step. A stop between steps can leave them disagreeing, for example money taken but no receipt.`,
     choices: [
-      { id: "all-or-nothing", label: "All or nothing", means: "Every change this action makes is saved together or not at all; Yichus stops it at each step and checks nothing half-done stays saved." },
+      {
+        id: "all-or-nothing",
+        label: "All or nothing",
+        means: "Every change this action makes is saved together or not at all; Yichus stops it at each step and checks nothing half-done stays saved.",
+        unchecked: "Requests and starting records the failure scenario does not list."
+      },
       { id: "partial-ok", label: "Partial is fine", means: "No check is added for this action." }
     ],
     fact: `${route.handler} writes ${tables.map((t) => `"${t}"`).join(", ")} in more than one step.`
@@ -1406,13 +1455,26 @@ function outsideQuestion(route, kinds, names) {
     ask: `"${shown(names, route.path)}" calls ${service}. If that service is down or slow, what should the person using your app see?`,
     why: "Outside services fail often. Without a plan, a failure can leave a half-finished record or charge for work that never happened.",
     choices: [
-      { id: "fail-clean", label: "An error, with nothing saved", means: "Yichus makes the service fail and checks that nothing from this action stays saved." },
-      { id: "finish-later", label: "Save the request and finish it later", means: "Yichus makes the service fail and checks the saved request is tried again and finished exactly once." },
+      {
+        id: "fail-clean",
+        label: "An error, with nothing saved",
+        means: "Yichus makes the service fail and checks that nothing from this action stays saved.",
+        unchecked: "Requests, starting records and answers from the service that the failure scenario does not list."
+      },
+      {
+        id: "finish-later",
+        label: "Save the request and finish it later",
+        means: "Yichus makes the service fail and checks the saved request is tried again and finished exactly once.",
+        unchecked: "Requests, starting records and answers from the service that the failure scenario does not list."
+      },
       { id: "no-plan", label: "No preference", means: "No check is added for this action." }
     ],
     fact: `${route.handler} reaches ${kinds.join(" and ")}.`
   };
 }
+var writeSteps = (route) => route.inferredSteps.filter((s) => s.resource === "db" && s.op !== "read" && s.op !== "query");
+var touchedBy = (route) => [.../* @__PURE__ */ new Set([...route.tables, ...route.inferredSteps.filter((s) => s.resource === "db").flatMap((s) => s.tables)])];
+var changedBy = (route) => [...new Set(writeSteps(route).flatMap((s) => s.tables))];
 var PERSON_SIGNS_IN = /* @__PURE__ */ new Set(["authenticated", "publishable", "requires-roles"]);
 var signIn = {
   id: "sign-in",
@@ -1451,9 +1513,7 @@ function questionsFor(report, structure, names = {}) {
     if (both.length) questions.push(togetherQuestion(table, both, names));
   }
   for (const route of report.surface.routes) {
-    const writes = route.inferredSteps.filter((s) => s.resource === "db" && s.op !== "read" && s.op !== "query");
-    const tables = [...new Set(writes.flatMap((s) => s.tables))];
-    if (writes.length >= 2) questions.push(partialQuestion(route, tables, names));
+    if (writeSteps(route).length >= 2) questions.push(partialQuestion(route, changedBy(route), names));
   }
   for (const route of report.surface.routes) {
     const entry = structure.entries.find((e) => e.entry === `route:${route.path}`);
@@ -1681,7 +1741,7 @@ var LawCheck = z6.looseObject({
   notSampled: z6.array(z6.looseObject({ binding: z6.string() })).optional(),
   reach: z6.array(z6.looseObject({ binding: z6.string(), usedBy: z6.array(z6.string()) })).optional()
 });
-var caseFile = (root, questionId) => path3.join(studioDir(root), "cases", `${questionId.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "")}.json`);
+var caseFile = (root, questionId) => path3.join(studioDir(root), "cases", `${questionId.replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-|-$/g, "")}.json`);
 var answerOf = (requirements, id) => requirements.answers.find((a) => a.question === id) ?? null;
 function instancesFor(requirements) {
   const choice = answerOf(requirements, "topology")?.choice;
@@ -1734,6 +1794,7 @@ async function judge(root, engine, sources, question, saved, report, verify, tog
           evidence: personal.map((r) => `${r.path} reaches "${question.subject}" and is called ${r.authority === "requires-roles" ? "by a person with a role" : "by a person"}, not by the app's own server.`)
         };
       }
+      if (answer.choice === "public") return { ...base, status: "no-check", check };
       const prop = byId(`access:${question.subject}`) ?? byId("access-coverage");
       if (!prop) return { ...base, status: "inconclusive", check: "api_verify", evidence: ["api_verify reported no access property for this table."] };
       return {
@@ -1759,35 +1820,47 @@ async function judge(root, engine, sources, question, saved, report, verify, tog
     case "partial":
     case "outside": {
       if (answer.choice === "partial-ok" || answer.choice === "no-plan") return { ...base, status: "no-check" };
-      const file = caseFile(root, question.id);
-      const rel = path3.relative(root, file).split(path3.sep).join("/");
-      if (!fs3.existsSync(file)) return { ...base, casePath: rel, status: "needs-case", check: "api_protocol_check", evidence: [`No protocol case at ${rel} yet.`] };
-      let protocolCase;
-      try {
-        protocolCase = JSON.parse(fs3.readFileSync(file, "utf8"));
-      } catch (error) {
-        return {
-          ...base,
-          casePath: rel,
-          check: "api_protocol_check",
-          status: "inconclusive",
-          evidence: [`${rel} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`]
-        };
-      }
-      const result = Protocol.parse(await engine.call("api_protocol_check", { sources: [...sources, ...caseSources(root)], case: protocolCase }));
-      const status = result.protocol?.status;
-      const check = `api_protocol_check ${rel}`;
-      if (!status) return { ...base, casePath: rel, check, status: "inconclusive", evidence: [result.error ?? "The protocol check gave no status."] };
-      return {
-        ...base,
-        casePath: rel,
-        check,
-        evidence: [`${result.protocol?.name ?? rel}: ${status}`],
-        status: status === "holds" ? "bounded" : status === "violated" ? "broken" : "inconclusive"
-      };
+      const ran = await runCase(root, engine, sources, question.id);
+      return { ...base, casePath: ran.casePath, check: ran.check, status: ran.status, evidence: ran.evidence };
     }
   }
 }
+var CaseRequests = z6.looseObject({ requests: z6.array(z6.looseObject({ call: z6.looseObject({ binding: z6.string() }) })) });
+async function runCase(root, engine, sources, id, runs = []) {
+  const file = caseFile(root, id);
+  const casePath = path3.relative(root, file).split(path3.sep).join("/");
+  if (!fs3.existsSync(file)) return { casePath, status: "needs-case", check: "api_protocol_check", evidence: [`No protocol case at ${casePath} yet.`] };
+  let protocolCase;
+  try {
+    protocolCase = JSON.parse(fs3.readFileSync(file, "utf8"));
+  } catch (error) {
+    return {
+      casePath,
+      check: "api_protocol_check",
+      status: "inconclusive",
+      evidence: [`${casePath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+  const called = CaseRequests.safeParse(protocolCase);
+  const bindings = called.success ? called.data.requests.map((r) => r.call.binding) : [];
+  const missing = runs.filter((r) => !bindings.includes(r.binding));
+  if (missing.length) return {
+    casePath,
+    check: "api_protocol_check",
+    status: "needs-case",
+    evidence: missing.map((r) => `${casePath} sends no request to ${r.path} (${r.binding}) yet.`)
+  };
+  const result = Protocol.parse(await engine.call("api_protocol_check", { sources: [...sources, ...caseSources(root)], case: protocolCase }));
+  const status = result.protocol?.status;
+  const check = `api_protocol_check ${casePath}`;
+  if (!status) return { casePath, check, status: "inconclusive", evidence: [result.error ?? "The protocol check gave no status."] };
+  return {
+    casePath,
+    check,
+    evidence: [`${result.protocol?.name ?? casePath}: ${status}`],
+    status: status === "holds" ? "bounded" : status === "violated" ? "broken" : "inconclusive"
+  };
+}
 var reason = (result) => typeof result.error === "string" ? result.error : "no reason given";
 async function checkLaws(engine, sources) {
   const answer = async (mode) => {
@@ -1826,14 +1899,27 @@ async function checkLaws(engine, sources) {
 }
 var lawNamed = (laws, ref) => laws.find((l) => l.binding === ref || l.binding.endsWith(`::${ref}`) || l.name === ref);
 var unused = (law) => law.usedBy !== null && !law.usedBy.length;
-function judgeRule(rule, laws) {
+async function judgeRule(rule, laws, report, root, engine, sources) {
   const found = rule.laws.map((ref) => [ref, lawNamed(laws, ref)]);
   const missing = found.filter(([, law]) => !law).map(([ref]) => ref);
   const checked = found.flatMap(([, law]) => law ? [law] : []);
   const evidence = [...missing.map((ref) => `No law named ${ref} in the program.`), ...checked.flatMap((l) => l.evidence.map((e) => `${l.name ?? l.binding}: ${e}`))];
   const status = missing.length || !checked.length ? "needs-law" : checked.some((l) => l.status === "broken") ? "broken" : checked.some((l) => l.status === "inconclusive") ? "inconclusive" : checked.some(unused) ? "unused" : checked.every((l) => l.status === "proven") ? "proven" : "bounded";
-  return { ...rule, status, evidence };
-}
+  if (status !== "proven" && status !== "bounded") return { ...rule, status, evidence };
+  const reachKnown = checked.every((l) => l.usedBy !== null);
+  const own = new Set(checked.flatMap((l) => l.usedBy ?? []).flatMap((entry) => entry.startsWith("route:") ? [entry.slice("route:".length)] : []));
+  const routes = report.surface.routes;
+  const records = new Set(reachKnown ? routes.filter((r) => own.has(r.path)).flatMap(touchedBy) : routes.flatMap(changedBy));
+  const others = routes.filter((r) => !own.has(r.path) && changedBy(r).some((t) => records.has(t)));
+  if (!others.length) return { ...rule, status, evidence };
+  const runs = routes.filter((r) => own.has(r.path) || others.includes(r)).map((r) => ({ path: r.path, handler: r.handler, binding: handlerOf(report, r) }));
+  const ran = await runCase(root, engine, sources, `rule:${rule.rule}`, runs);
+  const across = { casePath: ran.casePath, actions: runs.map((r) => r.path), others: others.map((r) => r.path) };
+  const changed = [...records].filter((t) => others.some((r) => changedBy(r).includes(t))).map((t) => `"${t}"`).join(", ");
+  const changing = reachKnown ? `${others.map((r) => r.path).join(", ")} ${others.length === 1 ? "changes" : "change"} ${changed} without deciding with the rule's laws.` : `Which actions decide with the rule's laws is not known, so its scenario runs every action that changes ${changed}.`;
+  return { ...rule, across, evidence: [...evidence, changing, ...ran.evidence], status: ran.status };
+}
+var keepRule = (actions) => `every one of ${actions.join(", ")} keep the rule, deciding with the same functions as its laws. Change the code, never the scenario's rule.`;
 var USE_THE_LAW = "If the function the law checks is in the program, make the action the rule is about decide with it. If it is defined next to the law, move it into the program, have the law check it there, and make the action decide with it. Never weaken what the law says.";
 var QUESTION_PROPERTIES = (id) => id.startsWith("access:") || id === "access-coverage" || id === "rmw-transactions" || id === "integrity";
 var GUIDE = {
@@ -1842,6 +1928,12 @@ var GUIDE = {
   partial: "Transaction protocols: finite cases, retries, and receipts",
   outside: "Transaction protocols: finite cases, retries, and receipts"
 };
+var DIRECTED_TOOLS = {
+  addRule: "api_add_rule",
+  deploy: "api_deploy",
+  suggestProperties: "api_suggest_properties",
+  protocolCheck: "api_protocol_check"
+};
 var SCAFFOLD_ARGS = {
   package_name: "My/App/Api",
   service_name: "my_app",
@@ -1938,7 +2030,7 @@ function nextStep(state, compileErrors, say2 = MCP) {
     instructions: [
       ...mismatched.map((p) => {
         const rule = ACCESS_RULES[p.answer.choice];
-        return `Make the AccessSpec rule for "${p.question.subject}" ${rule.write}${p.answer.choice === "server-only" ? ", and reach it only from worker routes" : ""} (${say2.api("api_add_rule")} for the snippet; ${say2.api("api_guide", { section: rule.guide })} for what it means).`;
+        return `Make the AccessSpec rule for "${p.question.subject}" ${rule.write}${p.answer.choice === "server-only" ? ", and reach it only from worker routes" : ""} (${say2.api(DIRECTED_TOOLS.addRule)} for the snippet; ${say2.api("api_guide", { section: rule.guide })} for what it means).`;
       }),
       next
     ],
@@ -1947,7 +2039,7 @@ function nextStep(state, compileErrors, say2 = MCP) {
   const broken = state.properties.filter((p) => p.status === "broken" || p.status === "inconclusive");
   const failing = state.other.filter((o) => o.status !== "warning");
   const warnings = state.other.filter((o) => o.status === "warning");
-  const brokenRules = state.rules.filter((r) => r.status !== "proven" && r.status !== "bounded");
+  const brokenRules = state.rules.filter((r) => r.status !== "proven" && r.status !== "bounded" && r.status !== "needs-case");
   const ruled = new Set(state.rules.flatMap((r) => r.laws.flatMap((ref) => lawNamed(state.laws, ref)?.binding ?? [])));
   const brokenLaws = state.laws.filter((l) => !ruled.has(l.binding) && (l.status === "broken" || l.status === "inconclusive" || unused(l)));
   const notHolding = broken.length + failing.length + brokenRules.length + brokenLaws.length + (state.lawsError ? 1 : 0);
@@ -1962,7 +2054,7 @@ function nextStep(state, compileErrors, say2 = MCP) {
       ...broken.map((p) => `"${p.question.ask}" The person chose "${p.question.choices.find((c) => c.id === p.answer?.choice)?.label}".${GUIDE[p.question.kind] ? ` ${capital(say2.api("api_guide", { section: GUIDE[p.question.kind] }))} for how.` : ""}`),
       ...failing.map((o) => `${o.title} (${o.id}) is ${o.status}.`),
       ...warnings.map((o) => `${o.title} (${o.id}) is a warning, not a failure: read its evidence. Change the code if it shows something the person did not choose, such as a stored field an action gives away; otherwise tell the person what it means.`),
-      ...brokenRules.map((r) => r.status === "needs-law" ? `The person's rule "${r.rule}" has no law in the program that checks it. Write one (${say2.reference("laws")} for how), then record the rules again with ${say2.name("yichus_rules")}.` : r.status === "unused" ? `The person's rule "${r.rule}" is checked by a law whose check calls nothing any action of the app reaches, so the law says nothing about what the app's actions do. ${USE_THE_LAW}` : `The person's rule "${r.rule}" is ${r.status === "broken" ? "broken: a law that states it fails" : "not decided by its laws"}. Change the code, never the law.`),
+      ...brokenRules.map((r) => r.status === "needs-law" ? `The person's rule "${r.rule}" has no law in the program that checks it. Write one (${say2.reference("laws")} for how), then record the rules again with ${say2.name("yichus_rules")}.` : r.status === "unused" ? `The person's rule "${r.rule}" is checked by a law whose check calls nothing any action of the app reaches, so the law says nothing about what the app's actions do. ${USE_THE_LAW}` : r.across ? r.status === "broken" ? `The person's rule "${r.rule}" is broken: its laws pass, and the scenario that runs every action that changes its records fails. Make ${keepRule(r.across.actions)}` : `The person's rule "${r.rule}" is not decided by the scenario that runs every action that changes its records. If the evidence shows ${r.across.casePath} itself is refused, fix that file, never its rule; otherwise make ${keepRule(r.across.actions)}` : `The person's rule "${r.rule}" is ${r.status === "broken" ? "broken: a law that states it fails" : "not decided by its laws"}. Change the code, never the law.`),
       ...brokenLaws.map((l) => `The law ${l.name ? `"${l.name}" (${l.binding})` : l.binding} ${l.status === "broken" ? "is broken. Change the code, never the law." : l.status === "inconclusive" ? "is not decided. Change the code, never the law." : `checks code no action of the app reaches. ${USE_THE_LAW}`}`),
       ...state.lawsError ? ["The engine could not check the program's laws, so no rule the person stated is checked. If the error below points at the program, fix the program; otherwise tell the person their rules are not checked yet."] : [],
       `Never weaken a rule, delete a check, a law or a claim, or declare one server to make a check pass: change the code. ${next}`
@@ -2021,13 +2113,15 @@ function nextStep(state, compileErrors, say2 = MCP) {
     ]
   };
   const cases = state.properties.filter((p) => p.status === "needs-case");
-  if (cases.length) return {
+  const ruleCases = state.rules.flatMap((r) => r.status === "needs-case" && r.across ? [{ rule: r.rule, ...r.across }] : []);
+  if (cases.length || ruleCases.length) return {
     stage: "write-case",
-    summary: "Writing the failure scenarios that test your answers.",
+    summary: cases.length ? "Writing the failure scenarios that test your answers." : "Writing a scenario that runs every action that changes the records your rules are about.",
     instructions: [
       `${capital(say2.reference("protocol-case"))}: it gives the case specification and a complete worked case with its program.`,
       "Put any Bosatsu observation predicates the case names in .yichus/cases/*.bosatsu. The studio adds those files to protocol checks only, so they never count as part of the app.",
       ...cases.map((p) => `Write ${p.casePath}: a protocol-case-1.0 for ${p.question.subject} whose invariants state the person's choice ("${p.question.choices.find((c) => c.id === p.answer?.choice)?.label}"), with crashes${p.question.kind === "outside" ? " and failed external results" : ""} at each step.`),
+      ...ruleCases.map((c) => `Write ${c.casePath}: a protocol-case-1.0 for the person's rule "${c.rule}". ${c.others.join(", ")} ${c.others.length === 1 ? "changes" : "change"} the same records as the actions that decide with the rule, so the case sends a request to every one of ${c.actions.join(", ")}, from starting records where the rule matters (one spot left, say), and its invariant states the rule over the records after every step: for a limit, what each record counts matches the records it counts, and never passes the limit. Write the observation predicate from the rule, not from the code.`),
       `State the person's rule exactly; never weaken it to match the code. ${next}`
     ]
   };
@@ -2041,7 +2135,7 @@ function nextStep(state, compileErrors, say2 = MCP) {
       ...assumed.length ? ["Say plainly which results depend on running exactly one server."] : [],
       ...data === "move" || data === "same-database" ? [`Before any record moves, list for the person every kind of record the old place keeps that this app does not (for example timestamps or a message log), and ask about each: add it to the app, or agree to leave it behind. ${capital(say2.reference("porting"))} says how to bring the data over.`] : [],
       `When they describe a new feature, change the code and ${say2.use("yichus_next")} again: new facts can raise new questions.`,
-      sections.length ? `When they want the app online, follow the ${sectionsText(sections)} section${sections.length === 1 ? "" : "s"} of the deploy reference (${say2.reference("deploy")}), and ${say2.api("api_deploy")} to generate the server.` : `The program keeps no records and has no actions people call, so it needs no server. When they want it on a page, ${say2.reference("calculator")}.`
+      sections.length ? `When they want the app online, follow the ${sectionsText(sections)} section${sections.length === 1 ? "" : "s"} of the deploy reference (${say2.reference("deploy")}), and ${say2.api(DIRECTED_TOOLS.deploy)} to generate the server.` : `The program keeps no records and has no actions people call, so it needs no server. When they want it on a page, ${say2.reference("calculator")}.`
     ]
   };
 }
@@ -2109,7 +2203,7 @@ async function direct({ root, engine, requirements, withMap = true, previous = n
       const checked = await checkLaws(engine, sources);
       base.laws = checked.laws;
       base.lawsError = checked.error;
-      base.rules = (requirements.rules ?? []).map((r) => judgeRule(r, base.laws));
+      for (const rule of requirements.rules ?? []) base.rules.push(await judgeRule(rule, base.laws, report, root, engine, sources));
       base.hasActions = report.surface.routes.length > 0;
       let access = null;
       if (base.hasActions || requirements.scenarios?.length) {
@@ -2158,6 +2252,7 @@ function readState(root) {
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z as z10 } from "zod";
+import { OpenFamilies } from "@yichus/api-mcp";
 
 // src/studio/marks.ts
 import fs4 from "fs";
@@ -2310,6 +2405,7 @@ function recordMarks(root, args, now) {
 }
 
 // src/studio/page.ts
+var HOLDING = ["proven", "bounded", "assumed", "no-check"];
 var PAGE_STATUS = {
   unanswered: ["waiting for your answer", "quiet"],
   decided: ["decided", "good"],
@@ -2325,6 +2421,9 @@ var PAGE_STATUS = {
   "no-check": ["no check needed", "quiet"],
   pending: ["answered, waiting for your agent to check", "quiet"]
 };
+function ruleUnchecked(across) {
+  return `Anything in your words that its laws do not state: your agent wrote the laws from your words.${across ? " Across actions, only the starting records and requests its scenario lists." : ""}`;
+}
 var PAGE_HEADINGS = {
   asked: "What you asked for",
   now: "What is happening now",
@@ -2474,6 +2573,7 @@ import { mount } from './system-map.js';
 import { mountSections, mountWhatHappens, reportViewing, showMarks } from './studio-views.js';
 
 const STATUS = ${JSON.stringify(PAGE_STATUS)};
+const HOLDING = ${JSON.stringify(HOLDING)};
 const NO_ACTIONS = ${JSON.stringify(NO_ACTIONS)};
 const el = (tag, props = {}, ...kids) => { const n = Object.assign(document.createElement(tag), props); n.append(...kids); return n; };
 let mapHash = null, drawn = '';
@@ -2508,7 +2608,9 @@ function questionCard(q, saved) {
 function ruleRow(r) {
   const [words, tone] = STATUS[r.status];
   const li = el('li', {}, el('span', { textContent: 'A rule you gave: ' }, el('em', { textContent: r.rule })), el('span', { className: 'chip ' + tone, textContent: words }));
-  li.append(el('span', { className: 'choice-said', textContent: 'Checked with ' + (r.laws === 1 ? '1 law' : r.laws + ' laws') + ' your agent wrote.' }));
+  li.append(el('span', { className: 'choice-said', textContent: 'Checked with ' + (r.laws === 1 ? '1 law' : r.laws + ' laws') + ' your agent wrote'
+    + (r.across ? ', and a scenario that runs every action that changes these records.' : '.') }));
+  if (r.unchecked) li.append(el('span', { className: 'choice-said', textContent: 'Not checked: ' + r.unchecked }));
   return li;
 }
 
@@ -2520,6 +2622,8 @@ function propertyRow(p, saved) {
   const li = el('li', {}, el('span', { textContent: p.question.ask }), el('span', { className: 'chip ' + tone, textContent: words }));
   li.dataset.property = p.question.id;
   li.append(el('span', { className: 'choice-said', textContent: 'You chose: ' + label + (answer.words && answer.words !== label ? ' ("' + answer.words + '")' : '') }));
+  const unchecked = !stale && HOLDING.includes(p.status) && p.question.choices.find(c => c.id === answer.choice)?.unchecked;
+  if (unchecked) li.append(el('span', { className: 'choice-said', textContent: 'Not checked: ' + unchecked }));
   return li;
 }
 
@@ -2682,13 +2786,16 @@ function pageText(root, pageUrl, now, surface) {
   const chosen = (state?.properties ?? []).filter((p) => p.answer || savedOf(p.question.id));
   const rules = state?.rules ?? [];
   if (!chosen.length && !rules.length) out.push("No properties chosen yet.");
-  for (const r of rules) out.push(`A rule the person gave: "${r.rule}" Status: ${PAGE_STATUS[r.status][0]}. Checked with ${r.laws.length === 1 ? "1 law" : `${r.laws.length} laws`} you wrote.`);
+  for (const r of rules) {
+    out.push(`A rule the person gave: "${r.rule}" Status: ${PAGE_STATUS[r.status][0]}. Checked with ${r.laws.length === 1 ? "1 law" : `${r.laws.length} laws`} you wrote${r.across ? `, and a scenario that runs every action that changes these records (${r.across.actions.join(", ")})` : ""}.${r.status === "proven" || r.status === "bounded" ? ` Not checked: ${ruleUnchecked(r.across !== void 0)}` : ""}`);
+  }
   for (const p of chosen) {
     const saved = savedOf(p.question.id);
     const stale = saved && (!p.answer || p.answer.answeredAt !== saved.answeredAt);
     const answer = stale ? saved : p.answer;
     const label2 = p.question.choices.find((c) => c.id === answer.choice)?.label ?? answer.choice;
-    out.push(`question ${p.question.id}: ${p.question.ask} Status: ${PAGE_STATUS[stale ? "pending" : p.status][0]}. They chose ${label2}${answer.words && answer.words !== label2 ? ` ("${answer.words}")` : ""}.`);
+    const unchecked = !stale && HOLDING.includes(p.status) && p.question.choices.find((c) => c.id === answer.choice)?.unchecked;
+    out.push(`question ${p.question.id}: ${p.question.ask} Status: ${PAGE_STATUS[stale ? "pending" : p.status][0]}. They chose ${label2}${answer.words && answer.words !== label2 ? ` ("${answer.words}")` : ""}.${unchecked ? ` Not checked: ${unchecked}` : ""}`);
   }
   heading("happens");
   const step = (s, pad) => {
@@ -2811,12 +2918,20 @@ var reference_default = {
     ]
   },
   "protocol-case": {
-    about: "The failure scenarios the studio checks for an action that must be all or nothing, or must survive an outside service failing: the case format and a complete worked case.",
+    about: "The scenarios the studio checks for an action that must be all or nothing or must survive an outside service failing, and for a rule other actions could go around: the case format and complete worked cases.",
     files: [
       { name: "protocol-cases.md", from: "docs/studio/protocol-cases.md" },
       { name: "protocol-specification.md", from: "docs/protocol-verification.md", sections: ["Case format: protocol-case-1.0", "Observation predicates", "Trace assertions", "Reachability witnesses", "Interpretation and limits"] },
       { name: "withdrawal-case.json", from: "eval/corpus/webmcp-traps/iteration-003/programs/Q15/twin/case.json" },
-      { name: "withdrawal.bosatsu", from: "eval/corpus/webmcp-traps/iteration-003/programs/Q15/twin/ledger.bosatsu" }
+      { name: "withdrawal.bosatsu", from: "eval/corpus/webmcp-traps/iteration-003/programs/Q15/twin/ledger.bosatsu" },
+      { name: "signups.bosatsu", from: "docs/studio/laws-example/signups/signups.bosatsu" },
+      { name: "signups-laws.bosatsu", from: "docs/studio/laws-example/signups/signups-laws.bosatsu" },
+      { name: "signups-case.json", from: "docs/studio/laws-example/signups/cases/signups-case.json" },
+      { name: "spots.bosatsu", from: "docs/studio/laws-example/signups/cases/spots.bosatsu" },
+      { name: "near-miss-signups.bosatsu", from: "docs/studio/laws-example/signups/near-miss/signups.bosatsu" },
+      { name: "near-miss-case.json", from: "docs/studio/laws-example/signups/cases/near-miss-case.json" },
+      { name: "mutants/double-signup.bosatsu", from: "docs/studio/laws-example/signups/mutants/double-signup.bosatsu" },
+      { name: "mutants/overfill.bosatsu", from: "docs/studio/laws-example/signups/mutants/overfill.bosatsu" }
     ]
   },
   calculator: {
@@ -2894,7 +3009,7 @@ function stepText(state, pageUrl) {
   }
   if (state.rules.length) {
     lines.push("", "Rules the person stated:");
-    for (const r of state.rules) lines.push(`  "${r.rule}" (${r.laws.join(", ")}): ${STATUS_WORDS[r.status]}`);
+    for (const r of state.rules) lines.push(`  "${r.rule}" (${[...r.laws, ...r.across ? [r.across.casePath] : []].join(", ")}): ${STATUS_WORDS[r.status]}`);
   }
   if (pageUrl) lines.push("", `Studio page: ${pageUrl}`);
   return `${lines.join("\n")}
@@ -2917,7 +3032,7 @@ The loop:
 8. While you talk with the person, point at what you mean on the studio page with yichus_point: a section of their app, an action, or a step in one, with a sentence or two as you would say it in the chat. The page shows each note over the pictures as yours, not checked, so never use a note to say something holds; the checks say that. Point again as the conversation moves on, and clear the marks when they no longer help.
 9. You drive the conversation, and the person reads the studio page while you talk. Call yichus_page to see what the page shows them, in words: what they asked for, the questions, each property with its status, what happens in each action, the sections of their app, your notes, and what they have on screen and last clicked. Call it whenever they refer to something on the page ("this one", "the red one", "what does that mean"), and after they answer on the page.
 
-Every api_* tool is available too. Leave out sources and the studio supplies the project's files. Pages on yich.us, such as calculators and the playground, come through a separate connection (@yichus/mcp); building needs only this one.`;
+The core api_* tools are listed too, and api_tools opens a specialist family (access, concurrency, proofs and more): its tools join the list. Leave out sources and the studio supplies the project's files. Pages on yich.us, such as data apps and the playground, come through a separate connection (@yichus/mcp); building needs only this one.`;
 var START = {
   name: "yichus_start",
   description: "Record what the person wants built, in their own words, and get the studio page link to give them. Call this first.",
@@ -3086,7 +3201,7 @@ function pageNote(pageUrl, say2) {
   ].join("\n");
 }
 function createStudioMcpServer({ root, engine, catalog, pageUrl, now = () => /* @__PURE__ */ new Date(), locate = builtCopy }) {
-  const server = new Server({ name: "yichus-studio", version: "0.3.3" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+  const server = new Server({ name: "yichus-studio", version: "0.3.4" }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
   const active = /* @__PURE__ */ new Set();
   const track = (task) => {
     active.add(task);
@@ -3094,10 +3209,12 @@ function createStudioMcpServer({ root, engine, catalog, pageUrl, now = () => /*
     });
     return task;
   };
-  let tools = null;
-  const catalogTools2 = async () => tools ??= (await catalog()).map(studioTool);
+  let entries = null;
+  const catalogEntries2 = async () => entries ??= (await catalog()).map((e) => ({ ...e, tool: studioTool(e.tool) }));
+  const catalogTools = async () => (await catalogEntries2()).map((e) => e.tool);
+  const families = new OpenFamilies(false, Object.values(DIRECTED_TOOLS));
   let last = readState(root);
-  server.setRequestHandler(ListToolsRequestSchema, () => track((async () => ({ tools: [START, NEXT, NAME, ANSWER, RULES, SCENARIO, POINT, PAGE, REFERENCE_TOOL, ...await catalogTools2()] }))()));
+  server.setRequestHandler(ListToolsRequestSchema, () => track((async () => ({ tools: [START, NEXT, NAME, ANSWER, RULES, SCENARIO, POINT, PAGE, REFERENCE_TOOL, ...families.listed(await catalogEntries2())] }))()));
   server.setRequestHandler(CallToolRequestSchema, (request) => track(callTool(request.params)));
   async function callTool(params) {
     const { name, arguments: args = {} } = params;
@@ -3142,7 +3259,7 @@ Next: call yichus_next.`, { pageUrl });
       return said2 ? text(said2) : text(`No reference topic ${String(args.topic)}.
 ${topicList((topic) => `topic "${topic}"`)}`, void 0, true);
     }
-    const tool = (await catalogTools2()).find((t) => t.name === name);
+    const tool = (await catalogTools()).find((t) => t.name === name);
     if (!tool) return text(`Unknown tool ${name}.`, void 0, true);
     const filled = { ...args };
     const props = tool.inputSchema.properties ?? {};
@@ -3152,15 +3269,7 @@ ${topicList((topic) => `topic "${topic}"`)}`, void 0, true);
     const topology2 = loadRequirements(root).answers.find((a) => a.question === "topology")?.choice;
     if ("instances" in props && filled.instances === void 0 && topology2) filled.instances = topology2 === "one" ? "1" : "many";
     const result = await engine.call(name, filled);
-    if (name === "api_guide" && filled.section === void 0 && Array.isArray(result.sections)) {
-      const titles = {
-        ok: true,
-        tool: "api_guide",
-        titles: result.sections.map((s) => s.title),
-        note: "The whole guide is long. Call api_guide with section set to one of these titles, or to part of one."
-      };
-      return text(JSON.stringify(titles), titles);
-    }
+    if (families.record(name, result)) await server.sendToolListChanged();
     return text(JSON.stringify(result), result, result.ok !== true);
   }
   return {
@@ -3645,16 +3754,22 @@ async function runCli(argv2, io) {
         timeoutMs
       ), "Lean result");
     } else {
-      if (opts.command === "call") {
-        const files = Array.isArray(args.sources) ? args.sources.length : void 0;
-        const progress = callProgress(opts.tool, files);
-        if (progress) io.stderr(progress);
-      }
+      const progress = opts.command === "call" ? callProgress(opts.tool, Array.isArray(args.sources) ? args.sources.length : void 0) : void 0;
+      let stageStart = io.now();
+      const finished = (stage) => {
+        const now = io.now();
+        io.stderr(`  ${stage} in ${((now - stageStart) / 1e3).toFixed(1)} s.
+`);
+        stageStart = now;
+      };
+      if (progress) io.stderr(progress);
       const engine = await io.loadEngine(opts.bundle);
+      if (progress) finished("Loaded the engine");
       if (opts.command === "call" && !Object.hasOwn(args, "sources") && readsProgram(engine, opts.tool)) {
         args.sources = folderSources(opts.tool, opts.project);
       }
-      const raw = opts.command === "tools" ? engine.listTools() : engine.callTool(opts.command === "verify" ? "api_verify" : opts.tool, JSON.stringify(args));
+      const tool = opts.command === "verify" ? "api_verify" : opts.tool;
+      const raw = opts.command === "tools" ? engine.listTools() : progress ? engine.callTool(tool, JSON.stringify(args), finished) : engine.callTool(tool, JSON.stringify(args));
       result = objectJson(raw, "Engine result");
     }
     if (typeof result.ok !== "boolean") throw new Error("Engine result must explicitly contain boolean ok");
@@ -3700,7 +3815,7 @@ async function runCli(argv2, io) {
 import { once } from "events";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { EngineWorkerClient, catalogTools } from "@yichus/api-mcp";
+import { EngineWorkerClient, catalogEntries } from "@yichus/api-mcp";
 
 // src/studio/page-server.ts
 import fs10 from "fs";
@@ -3726,7 +3841,13 @@ function personView(state, names, marks = null) {
       status: p.status
     })),
     // A state written before rules were kept has none.
-    rules: (state.rules ?? []).map((r) => ({ rule: r.rule, status: r.status, laws: r.laws.length })),
+    rules: (state.rules ?? []).map((r) => ({
+      rule: r.rule,
+      status: r.status,
+      laws: r.laws.length,
+      across: r.across !== void 0,
+      unchecked: r.status === "proven" || r.status === "bounded" ? ruleUnchecked(r.across !== void 0) : null
+    })),
     map: state.map ? relabelSystemMap(state.map, names) : null,
     mapError: state.mapError,
     sections,
@@ -3857,7 +3978,7 @@ function workerEngine(bundle) {
       return objectResult(await worker.callTool(tool, JSON.stringify(args), `studio-${++id}`), tool);
     },
     async catalog() {
-      return catalogTools(await worker.listTools(`studio-${++id}`));
+      return catalogEntries(await worker.listTools(`studio-${++id}`));
     },
     close: () => worker.close()
   };
@@ -3917,6 +4038,7 @@ process.exitCode = STUDIO_COMMANDS.has(argv[0] ?? "") ? await runStudioCommand(a
   // fails a synchronous read with EAGAIN on macOS.
   readStdin: () => text2(process.stdin),
   stdout: (text3) => process.stdout.write(text3),
-  stderr: (text3) => process.stderr.write(text3)
+  stderr: (text3) => process.stderr.write(text3),
+  now: () => performance.now()
 });
 //# sourceMappingURL=main.js.map