yichus 0.3.1 → 0.3.3

package/README.md

@@ -6,7 +6,7 @@ shipped in `@yichus/api-mcp`; installing the release requires Node 20+,
 without Java, sbt, Nix, or a browser.
 
 ```sh
-npm install --save-dev yichus@0.3.1
+npm install --save-dev yichus@0.3.3
 npx yichus tools
 npx yichus call api_guide
 ```
@@ -29,7 +29,7 @@ and the studio tells the agent what to do next after every change:
 ```json
 {
   "mcpServers": {
-    "yichus": { "command": "npx", "args": ["-y", "yichus@0.3.1", "studio"] }
+    "yichus": { "command": "npx", "args": ["-y", "yichus@0.3.3", "studio"] }
   }
 }
 ```
@@ -219,6 +219,9 @@ different folders are named by the folders that tell them apart
 Use `--args options.json` (or `--args -` for stdin) for the remaining
 arguments. Values retain their JSON types. You can supply a complete
 `sources` array there instead of `--source`; mixing the two is rejected.
+`--arg-file NAME=FILE` sets one argument to the JSON in a file, such as
+a saved snapshot for `api_snapshot` (`--arg-file snapshot=ledger.snap.json`);
+naming the same argument in `--args` too is rejected.
 
 ```json
 {"instances":"1"}

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../package.json","../src/node-version.ts","../src/cli.ts"],"sourcesContent":["{\n  \"name\": \"yichus\",\n  \"version\": \"0.3.1\",\n  \"description\": \"Local Bosatsu compilation, Yichus analysis, and generated apps using the WebMCP engine\",\n  \"license\": \"MIT\",\n  \"homepage\": \"https://yich.us\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/snoble/yichus.git\",\n    \"directory\": \"packages/yichus-cli\"\n  },\n  \"type\": \"module\",\n  \"bin\": {\n    \"yichus\": \"./dist/cli.js\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup && node ./scripts/copy-studio-assets.mjs\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run --coverage\",\n    \"prepack\": \"npm run build\"\n  },\n  \"dependencies\": {\n    \"@yichus/api-mcp\": \"workspace:*\",\n    \"zod\": \"^4.3.6\",\n    \"@modelcontextprotocol/sdk\": \"^1.26.0\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^22.0.0\",\n    \"tsup\": \"^8.3.0\",\n    \"typescript\": \"^5.6.0\",\n    \"vitest\": \"^2.1.0\",\n    \"@vitest/coverage-v8\": \"2.1.9\"\n  },\n  \"engines\": {\n    \"node\": \">=20\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\"\n  }\n}\n","/**\n * The sentence that stops the command on a Node older than the package's\n * `engines.node` floor, or undefined when the running Node meets it.\n */\nexport function nodeVersionProblem(running: string, required: string): string | undefined {\n  const floor = /^>=(\\d+)$/.exec(required);\n  if (!floor) throw new Error(`engines.node must read >=N, not ${required}`);\n  const needed = Number(floor[1]);\n  if (Number(running.split('.')[0]) >= needed) return undefined;\n  return `yichus needs Node ${needed} or newer; this is Node ${running}. Install Node ${needed} or newer and run the command again.`;\n}\n","#!/usr/bin/env node\n// The Node check runs before the rest of the command loads, so an older\n// Node gets a sentence naming what to install rather than an error from\n// inside the engine.\nimport { engines } from '../package.json';\nimport { nodeVersionProblem } from './node-version.js';\n\nconst problem = nodeVersionProblem(process.versions.node, engines.node);\nif (problem) {\n  process.stderr.write(`${problem}\\n`);\n  process.exitCode = 1;\n} else {\n  await import('./main.js');\n}\n"],"mappings":";;;AAqCE,cAAW;AAAA,EACT,MAAQ;AACV;;;ACnCK,SAAS,mBAAmB,SAAiB,UAAsC;AACxF,QAAM,QAAQ,YAAY,KAAK,QAAQ;AACvC,MAAI,CAAC,MAAO,OAAM,IAAI,MAAM,mCAAmC,QAAQ,EAAE;AACzE,QAAM,SAAS,OAAO,MAAM,CAAC,CAAC;AAC9B,MAAI,OAAO,QAAQ,MAAM,GAAG,EAAE,CAAC,CAAC,KAAK,OAAQ,QAAO;AACpD,SAAO,qBAAqB,MAAM,2BAA2B,OAAO,kBAAkB,MAAM;AAC9F;;;ACHA,IAAM,UAAU,mBAAmB,QAAQ,SAAS,MAAM,QAAQ,IAAI;AACtE,IAAI,SAAS;AACX,UAAQ,OAAO,MAAM,GAAG,OAAO;AAAA,CAAI;AACnC,UAAQ,WAAW;AACrB,OAAO;AACL,QAAM,OAAO,WAAW;AAC1B;","names":[]}
+{"version":3,"sources":["../package.json","../src/node-version.ts","../src/cli.ts"],"sourcesContent":["{\n  \"name\": \"yichus\",\n  \"version\": \"0.3.3\",\n  \"description\": \"Local Bosatsu compilation, Yichus analysis, and generated apps using the WebMCP engine\",\n  \"license\": \"MIT\",\n  \"homepage\": \"https://yich.us\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/snoble/yichus.git\",\n    \"directory\": \"packages/yichus-cli\"\n  },\n  \"type\": \"module\",\n  \"bin\": {\n    \"yichus\": \"./dist/cli.js\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup && node ./scripts/copy-studio-assets.mjs\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run --coverage\",\n    \"prepack\": \"npm run build\"\n  },\n  \"dependencies\": {\n    \"@yichus/api-mcp\": \"workspace:*\",\n    \"zod\": \"^4.3.6\",\n    \"@modelcontextprotocol/sdk\": \"^1.26.0\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^22.0.0\",\n    \"tsup\": \"^8.3.0\",\n    \"typescript\": \"^5.6.0\",\n    \"vitest\": \"^2.1.0\",\n    \"@vitest/coverage-v8\": \"2.1.9\"\n  },\n  \"engines\": {\n    \"node\": \">=20\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\"\n  }\n}\n","/**\n * The sentence that stops the command on a Node older than the package's\n * `engines.node` floor, or undefined when the running Node meets it.\n */\nexport function nodeVersionProblem(running: string, required: string): string | undefined {\n  const floor = /^>=(\\d+)$/.exec(required);\n  if (!floor) throw new Error(`engines.node must read >=N, not ${required}`);\n  const needed = Number(floor[1]);\n  if (Number(running.split('.')[0]) >= needed) return undefined;\n  return `yichus needs Node ${needed} or newer; this is Node ${running}. Install Node ${needed} or newer and run the command again.`;\n}\n","#!/usr/bin/env node\n// The Node check runs before the rest of the command loads, so an older\n// Node gets a sentence naming what to install rather than an error from\n// inside the engine.\nimport { engines } from '../package.json';\nimport { nodeVersionProblem } from './node-version.js';\n\nconst problem = nodeVersionProblem(process.versions.node, engines.node);\nif (problem) {\n  process.stderr.write(`${problem}\\n`);\n  process.exitCode = 1;\n} else {\n  await import('./main.js');\n}\n"],"mappings":";;;AAqCE,cAAW;AAAA,EACT,MAAQ;AACV;;;ACnCK,SAAS,mBAAmB,SAAiB,UAAsC;AACxF,QAAM,QAAQ,YAAY,KAAK,QAAQ;AACvC,MAAI,CAAC,MAAO,OAAM,IAAI,MAAM,mCAAmC,QAAQ,EAAE;AACzE,QAAM,SAAS,OAAO,MAAM,CAAC,CAAC;AAC9B,MAAI,OAAO,QAAQ,MAAM,GAAG,EAAE,CAAC,CAAC,KAAK,OAAQ,QAAO;AACpD,SAAO,qBAAqB,MAAM,2BAA2B,OAAO,kBAAkB,MAAM;AAC9F;;;ACHA,IAAM,UAAU,mBAAmB,QAAQ,SAAS,MAAM,QAAQ,IAAI;AACtE,IAAI,SAAS;AACX,UAAQ,OAAO,MAAM,GAAG,OAAO;AAAA,CAAI;AACnC,UAAQ,WAAW;AACrB,OAAO;AACL,QAAM,OAAO,WAAW;AAC1B;","names":[]}

package/dist/main.js

@@ -301,15 +301,16 @@ var VOCABULARY = {
     modelRing: "violet ring: the entry reaches the model  <- entries[].model",
     reachedBy: "under each resource in the rack: how many routes reach it, the resource drawn at that share of the routes (never smaller than its name)  <- entries[].db, model, net, beside.resources",
     netRing: "orange ring: the entry reaches the network  <- entries[].net",
-    guard: "red diamond on the path where the check happens, its name above, failure stem below  <- entries[].guards, wrappers[].guards, entries[].passed[].guards, entries[].beside.guards",
+    guard: 'red diamond on the path where the route can refuse, the check named above it (the program\u2019s definition it calls, "<table> row found", "<table> row\u2019s <field>" for a branch on a field of a read row, or "a test in <definition>" for a comparison or library answer that definition branches on), failure stem below; a branch no path refuses on is not drawn here  <- entries[].guards (structure.scenarios[]: branches where one arm ends only in refusals), wrappers[].guards, entries[].passed[].guards, entries[].beside.guards',
+    policy: "under the db, each table with its access policy as the access check proves it: own = each caller reads and writes only their own row; no row rule = the access check holds no rule over its rows, so who reads or writes which row is decided only by the code drawn on the routes; guarded = rows pass the named guard; role \u2026 only = only callers with that role reach its rows; unchecked = the access check gave this table no verdict; a policy ending \u201Cbroken\u201D is one the code breaks, and \u201Cnot proven\u201D one the check could not settle; counted when the tables are too many to list  <- resources[kind=db].policies",
     hull: "translucent region in the hull band: paths merge into it, run one shared stretch, and split; everything inside it runs inside the wrapper; its right wall, drawn in the hull ink, is where the wrapper returns  <- wrappers[]",
     socket: "broken-rim ring: a function the caller hands in runs here; its centre fills like a station  <- entries[].passed[]",
     token: "small grey word under a path: the value the caller fixes for the wrapper  <- entries[].policy",
     afterDot: "dot in the after band: a call the entry makes after its wrapper returns  <- entries[].beside.calls",
     builder: "plus-disc under a station with the call that builds the handle there  <- uses[how=local].builtBy",
     unknown: 'a ? in a circle on the rail, with "partly traced" beside it and a sentence on hover: the engine traced the handle only on some paths  <- uses[how=mixed]',
-    fork: "three prongs and a type: a choice keyed on a plain String or Int; under the mark that makes it, else on the quiet line  <- keyed[]",
-    bundle: 'one cable with how many routes it carries ("4 routes"): entries with the same wrapper and identical marks; its title names every route; opening it draws each one  <- bundles[]',
+    fork: 'three prongs and a type: a choice keyed on a plain String or Int; under the mark that makes it (under a list of checks, named by the check it is inside: "can_see on String"), else on the quiet line  <- keyed[]',
+    bundle: 'one cable with how many routes it carries ("4 routes"): entries with the same wrapper and identical marks; its title names every route: by the one part of the path that differs, among at most six ("/{tags, tasks}/sync"), or each by name when there are at most four; else a pattern with *; opening it draws each one  <- bundles[]',
     anchor: "where the rail starts: platform when no definition of the program can make the handle; ? when the trace stops and the program could  <- uses[].anchor",
     step: 'loop arc with a type on the quiet line: functions of the package take that type and return it; gathered, a count in words ("8 steps"), as are choices, db uses and generic parts  <- steps[]',
     loop: "loop arc with package names: packages whose types lead back to themselves  <- phases.cycles",
@@ -330,6 +331,7 @@ var VOCABULARY = {
     replyLoop: `one solid arc from a lane's foot back into the program, with one loop node naming what repeats the step within one call, and "each call of \u2026 runs it" naming the routes that run the rounds  <- programs[].engines[].replies, loop, starters`,
     replaced: 'a check named "(in place of \u2026)": in the compared base record the same route had that other check at the same place, and it is on that route no longer; says nothing about whether the two do the same  <- compare.replaced[]'
   },
+  names: "every check, call and table name is a label the code's author (often an AI) chose; the picture proves where a check runs, what it is given and what happens when it fails, never what it decides: a reader who doubts the author reads that rule itself.",
   rule: "every guard, wrapper, socket, fork, handle, station, step and resource the engine records is drawn at its fixed place, in every view; where nothing is drawn, the engine checked and found none."
 };
 var bare = (id) => String(id).split("::").pop();
@@ -449,9 +451,51 @@ function programsOf(st, layers = null) {
   });
 }
 var outsideResourcesOf = (steps) => uniq((steps || []).map((e) => e.resource).filter((r) => r === "model" || r === "net"));
+var leavesUnder = (t) => t.kind === "leaf" ? [t] : t.arms.flatMap((a) => leavesUnder(a.next));
+function refusingForks(tree) {
+  const out = [];
+  const go = (t) => {
+    if (!t || t.kind !== "node") return;
+    const refused = t.arms.map((a) => leavesUnder(a.next).every((l) => l.outcome.kind === "refused"));
+    if (t.concern?.layer !== "platform" && refused.some(Boolean) && !refused.every(Boolean)) out.push(t);
+    t.arms.forEach((a) => go(a.next));
+  };
+  go(tree);
+  return out;
+}
+var forkId = (n, own) => n.from.kind === "call" && own.has(n.from.callee) ? n.from.callee : n.id;
+var forkParts = (n, own) => n.from.kind === "call" && own.has(n.from.callee) ? { definition: n.from.callee } : n.from.kind === "read" && n.from.table ? { table: n.from.table, ...n.from.path?.length ? { field: n.from.path.join(".") } : {} } : n.from.site ? { definition: n.from.site } : {};
+var forkKey = (own) => (n) => n.from.kind === "call" && own.has(n.from.callee) ? n.from.callee : `${forkLabel(n, own)} ${n.from.site}`;
+var forkLabel = (n, own) => n.from.kind === "call" ? own.has(n.from.callee) ? bare(n.from.callee) : `a test in ${bare(n.from.site)}` : n.from.kind === "read" && n.from.table ? n.from.path?.length ? `${n.from.table} row\u2019s ${n.from.path.join(".")}` : `${n.from.table} row found` : n.from.site ? `a test in ${bare(n.from.site)}` : "a computed branch";
+var policyWord = (r) => {
+  const rule = policyRule(r);
+  if (rule === "unchecked") return rule;
+  return r.status === "violated" ? `${rule}, broken` : r.proven ? rule : `${rule}, not proven`;
+};
+var policyRule = (r) => {
+  const roles = () => r.roles.join(", "), guards = () => r.guards.join(", ");
+  switch (r.policyKind) {
+    case "OwnerScoped":
+      return "own";
+    case "Public":
+      return "no row rule";
+    case "Guarded":
+      return `guarded by ${guards()}`;
+    // with no guard, only the roles reach its rows
+    case "GuardedOrRoles":
+      return r.guards.length ? `guarded by ${guards()} or role ${roles()}` : `role ${roles()} only`;
+    case "PublicReadRoleWrite":
+      return `anyone reads; role ${roles()} writes`;
+    default:
+      return "unchecked";
+  }
+};
 function buildSystemMap(engine, { program }) {
   for (const [k, v] of Object.entries(engine)) if (!v.ok) throw new Error(`${k}: ${v.error}`);
   const report = engine.report, st = engine.structure, abs = engine.abstractions.abstractions, layers = engine.layers.layers;
+  const whole = (s) => s.tree && !s.truncated && !s.unsupported;
+  const trees = new Map((st.scenarios || []).filter(whole).map((s) => [s.entry, refusingForks(s.tree)]));
+  const ownDefs = new Set(layers.packages.flatMap((p) => p.definitions.map((d) => `${p.name}::${d.name}`)));
   const routes = (report.surface.routes || []).slice().sort((a, b) => a.path.localeCompare(b.path));
   const engEntry = new Map(st.entries.map((e) => [e.entry, e]));
   const shapes = new Map(abs.routeShapes.map((r) => [r.path, r]));
@@ -466,11 +510,17 @@ function buildSystemMap(engine, { program }) {
     resources: outsideResourcesOf(inst.besideEffectSteps),
     from: "abstractions.instantiations[].beside*"
   });
+  const resultOf = (sig) => sig.includes("->") ? sig.slice(sig.lastIndexOf("->") + 2).trim() : null;
+  const returnsCallers = (g) => {
+    const result = resultOf(g.signature);
+    return result !== null && (/^[a-z]\w*$/.test(result) || (g.parameterGroups || []).flat().some((sl) => sl.role === "function" && sl.returnType === result));
+  };
+  const wraps = (g) => !!g && (/\bIO\[/.test(g.signature) || g.envelope.effects.length > 0 || returnsCallers(g) && (g.envelope.guards.length > 0 || g.envelope.dispatchesOn.length > 0));
   const entries = routes.map((r) => {
     const key = `route:${r.path}`;
     const ee = engEntry.get(key);
     const rs = shapes.get(r.path);
-    const wrapper = rs.shapedByGenerator;
+    const wrapper = wraps(gens.get(rs.shapedByGenerator)) ? rs.shapedByGenerator : null;
     const inst = wrapper ? insts.find((i) => i.callerId === rs.handlerId && i.generatorId === wrapper) : null;
     const passed = (inst ? inst.slotBindings : []).filter((sb) => ["function", "effect"].includes(sb.slotRole)).map((sb) => ({
       slot: sb.slotName,
@@ -507,8 +557,9 @@ function buildSystemMap(engine, { program }) {
       model: ee.resources.includes("model"),
       net: ee.resources.includes("net"),
       writes: reach.some((e) => isWrite(e.op)),
-      guards: rs.handlerGuards.map(bare),
-      guardIds: rs.handlerGuards,
+      // every branch of the entry's own where a path refuses (a wrapper's are
+      // its own, and a function handed to it keeps its own slot)
+      ...trees.has(key) ? ((forks) => ({ guards: forks.map((n) => forkLabel(n, ownDefs)), guardIds: forks.map((n) => forkId(n, ownDefs)), guardParts: forks.map((n) => forkParts(n, ownDefs)) }))(uniqBy(trees.get(key).filter((n) => n.concern?.layer !== "cross" && !(inst ? inst.slotBindings : []).some((sb) => (sb.guards || []).includes(forkId(n, ownDefs)))), forkKey(ownDefs))) : { guards: rs.handlerGuards.map(bare), guardIds: rs.handlerGuards },
       wrapper,
       via: rs.viaSpecialization ? bare(rs.viaSpecialization) : null,
       policy: (inst ? inst.slotBindings : []).filter((s) => s.slotRole === "semantic-object").map((s) => s.value).filter(Boolean),
@@ -598,7 +649,12 @@ function buildSystemMap(engine, { program }) {
   }
   const present = uniq(st.ioKinds.flatMap((b) => b.resources));
   const tables = uniq(entries.flatMap((e) => [...e.reach, ...e.beside ? e.beside.effects : []].map((r) => r.table))).sort();
-  const resources = ["db", "model", "net"].filter((k) => present.includes(k)).map((k) => ({ kind: k, ...k === "db" ? { tables } : {}, from: "structure.ioKinds[].resources" }));
+  const policies = engine.access ? Object.fromEntries(engine.access.report.resources.filter((r) => tables.includes(r.resource)).map((r) => [r.resource, policyWord(r)])) : null;
+  const resources = ["db", "model", "net"].filter((k) => present.includes(k)).map((k) => ({
+    kind: k,
+    ...k === "db" ? { tables, ...policies ? { policies, policyFrom: "access.report.resources[].policyKind, guards, roles" } : {} } : {},
+    from: "structure.ioKinds[].resources"
+  }));
   const ghostResources = ["db", "model", "net"].filter((k) => !present.includes(k)).map((k) => ({ kind: k, from: "structure.ioKinds[] checked: no site of this kind" }));
   const transports = uniq(st.entries.map((e) => e.transport));
   const callers = [];
@@ -712,13 +768,22 @@ function bundlesOf(entries, uses, keyed) {
 }
 function pathPattern(paths) {
   if (paths.length === 1) return paths[0];
+  const sorted = [...paths].sort();
   const segs = paths.map((p) => p.split("/"));
   const n = Math.min(...segs.map((s) => s.length));
   const out = [];
+  const vary = [];
   for (let i = 0; i < n; i++) {
     const v = uniq(segs.map((s) => s[i]));
     out.push(v.length === 1 ? v[0] : "*");
+    if (v.length > 1) vary.push([i, v]);
+  }
+  if (segs.every((s) => s.length === n) && vary.length === 1 && vary[0][1].length <= 6) {
+    const [[i, v]] = vary;
+    out[i] = `{${[...v].sort().join(", ")}}`;
   }
+  if (segs.every((s) => s.length === n) && vary.length <= 1) return out.join("/");
+  if (paths.length <= 4) return sorted.join(", ");
   if (segs.every((s) => s.length === n)) return out.join("/");
   let k = 0;
   while (k < n && out[k] !== "*") k++;
@@ -750,6 +815,7 @@ var STRUCTURAL = /* @__PURE__ */ new Set([
   "vars",
   "id"
 ]);
+var DESCRIBED = /* @__PURE__ */ new Set(["guards", "policies", "policyFrom"]);
 var WHAT = {
   path: "an action the app answers",
   routes: "an action the app answers",
@@ -758,7 +824,8 @@ var WHAT = {
   roles: "a permission an action requires, held by a person's role or by the app's own server",
   policy: "a setting an action passes to shared code",
   tokens: "a setting an action passes to shared code",
-  fields: "an operation a pluggable part offers"
+  fields: "an operation a pluggable part offers",
+  field: "a field of a kind of record the app keeps"
 };
 var PACKAGE = "a section of the program";
 var DEFINITION = "a piece of the program";
@@ -781,7 +848,7 @@ var leaves = (record, visit) => {
     if (typeof v === "string") visit(v, key);
     else if (Array.isArray(v)) v.forEach((x) => walk3(x, key));
     else if (v && typeof v === "object") {
-      for (const [k, x] of Object.entries(v)) if (!skipped(k, x)) walk3(x, k);
+      for (const [k, x] of Object.entries(v)) if (!skipped(k, x) && !DESCRIBED.has(k)) walk3(x, k);
     }
   };
   walk3(record, null);
@@ -799,6 +866,7 @@ function nameableParts(map, own) {
     add(id.slice(i + 2), DEFINITION);
   };
   leaves(map, (s, key) => {
+    if (key === "guardIds" && s.startsWith("route:")) return;
     if (s.startsWith("route:")) return add(s.slice(6), WHAT.path);
     if (TYPES.has(key)) {
       for (const w of s.match(WORD) ?? []) if (w.includes("::")) idParts(w);
@@ -863,19 +931,22 @@ var VOCABULARY2 = {
   version: MARKS_VERSION,
   added: ["outcome"],
   marks: {
-    entryHead: "arrowhead where a request comes in; the rack above the tree has one per described entry, then one dashed line counting the entries no scenario describes, which opens to draw each of them struck  <- entries[], ghosts[]",
+    entryHead: 'arrowhead where a request comes in; the rack above the tree has one per described entry, then one dashed line counting the entries no scenario describes, which opens to draw each of them struck (when no entry is described, that one line is all the rack draws, and it only counts them: "8 entries"; a scenario is a requirement someone wrote, so its absence says nothing about tests); under the head, "same steps as \u2026" names the entries whose trees take the same steps on their own tables and checks  <- entries[], ghosts[], entries[].sameShape',
     guard: "red diamond: the declared sign-in or role check, the first branch of every entry that has one; its failure stem ends in a refusal  <- tree node with from.kind=guard",
-    fork: "three prongs: a branch the code takes on the request, the caller, a value read from a table, or a call result; the arm each line takes is written where it leaves  <- tree nodes",
-    station: "ring on a line: an effect on that path, its verb and table beside it; filled = it writes  <- arms[].effects, entry.effects",
+    fork: 'three prongs: a branch the code takes on the request, the caller, a value read from a table, or a call result, with "\u2190 request", "\u2190 caller" or "\u2190 <table> as read" saying where what it tests comes from; the arm each line takes is written where it leaves  <- tree nodes, nodes[].from.sources',
+    docs: "under the names line, in italic, the comment the author wrote above each named check, marked unchecked: what the author says it decides, which the engine does not confirm  <- docs (structure.docs)",
+    rows: `under the tree, for each table its stations touch (and those of the entries named in "same steps as"), what one row holds, by its checked type: "posts holds List[Post(id: String, \u2026, edited: Bool)]"; a field that is a record gives only its type's name, a choice of bare cases its cases ("visibility: Open | Members")  <- rows (structure.rows)`,
+    station: "ring on a line: an effect on that path, its verb and table beside it; filled = it writes; mint = the platform hands out a fresh row id. Under it, in grey, the row it touches (the caller's row; the row named by a request field; one fixed row; a new row; every row, and the guard that keeps them) and, for a write, whether the row is replaced whole or updated from what it read, then where what it writes comes from, field by field (\u2190 caller, \u2190 request.<field>, \u2190 a literal, \u2190 new id, \u2190 a call and what it was computed from)  <- arms[].effects[].key, value, kept (access report.findings[operation=keep_visible].provenBy)",
     modelRing: "violet ring: the path reaches the model  <- effects[resource=model]",
     netRing: "orange ring: the path reaches the network  <- effects[resource=net]",
     outcome: "the end of a path: a cap with what the request gets back (a constructor, or a refusal with its status and code); red when a claim fails there or a check reports a witness that ends there, green when every obligation that failed there at the base is checked here and holds, hollow and dashed (unchecked) when a claim there is inconclusive or an obligation that failed at the base is no longer checked, grey otherwise  <- leaves",
     unchecked: "a hollow dashed cap and a ? tick: the engine cannot say whether the claim holds on this path (a step it could not open, a table it could not name, an answer it could not decide), or what failed here at the base is not checked here; never counted as holding  <- claims[verdict=inconclusive], leaves[].gaps, diff.unresolved",
     struck: "a struck ghost: something checked and found absent (an entry nobody described, a write a claim says a path must not make)  <- ghosts[], claims holding with not",
     bundle: "a cable with a count: a subtree too large for this view; opening it draws that part with a breadcrumb  <- derived from the tree",
-    compared: 'a line under the rack, always there: "compared with <base> \xB7 N fixed \xB7 M still failing", or "no base compared" in faint text  <- diff',
+    compared: 'a line under the rack when a base was compared: "compared with <base> \xB7 N fixed \xB7 M still failing"; with no base, no line  <- diff',
     hull: `a shaded box on the line: a step that is not the handler's own work, folded (a wrapper's guard or short-circuit, the platform's declared check or the transaction it runs the plan in, work beside the wrapper, a wrapper's work after the handler); it keeps what the step answers instead of running the handler: the effects it makes before its test above the arms, then one row per arm read as a side stub (the arm, the effects that arm makes, its struck writes, what the request gets, ticks), then "continue"; opening it draws the step's own tree; drawn inline, the same hull is a light band behind the step and its exits, with its role and where it comes from above its test, so either way it reads as not the handler's own work  <- tree nodes[concern.role], entries[].steps`
   },
+  names: "every check, call and table name is a label the code's author (often an AI) chose; the picture proves where a check runs, what it is given and what happens when it fails, never what it decides: a reader who doubts the author reads that rule itself.",
   rule: "every entry, branch, arm, effect and outcome the engine computes is drawn, a folded step's inside its box and an undescribed entry behind the rack's one line; the author's words appear only on ids the engine computed, in italic, with the code name beside them.",
   concerns: "where each branch and effect comes from in value flow (concern.layer, effects[].layer): core = the handler's own work, a function it hands its wrapper or its body when it has none; cross = the wrapper its route shape names, shared with other entries; beside = the handler's code outside the wrapper call; platform = the route's declared authority, or the transaction the platform runs a plan in (its arms that give up or cannot confirm skip the handler's work). Roles come from which arms reach the handler, never from names."
 };
@@ -953,6 +1024,11 @@ function buildWhatHappens(engine, { program, base = null, baseLabel = "base" } =
   const claims = st.claims || { scenarios: [], undescribed: (st.scenarios || []).map((s) => s.entry) };
   const byEntry = new Map(claims.scenarios.filter((s) => s.status === "matched").map((s) => [s.entry, s]));
   const routes = new Map((st.entries || []).map((e) => [e.entry, e]));
+  const kept = new Map((engine.access?.report?.findings || []).filter((f) => f.operation === "keep_visible" && f.kind === "GuardProven" && f.status === "holds").map((f) => [`${f.package}::${f.binding}\0${f.resource}`, `${(f.provenBy || []).join(" and ")} passes for the caller and the row`]));
+  const withKept = (es) => es.map((e) => {
+    const by = e.kind === "DbQuery" && e.tables.length === 1 ? kept.get(`${e.site}\0${e.tables[0]}`) : null;
+    return by ? { ...e, kept: by } : e;
+  });
   const entries = st.scenarios.map((s) => {
     const meta = routes.get(s.entry) || {};
     const sc = byEntry.get(s.entry);
@@ -960,7 +1036,7 @@ function buildWhatHappens(engine, { program, base = null, baseLabel = "base" } =
     const copy = (t) => {
       if (!t) return null;
       if (t.kind === "leaf") return { ...t, words: names.get(t.id) || null, claims: [], witnesses: [], status: "grey" };
-      return { ...t, words: names.get(t.id) || null, arms: t.arms.map((a) => ({ ...a, words: names.get(a.id) || null, next: copy(a.next) })) };
+      return { ...t, words: names.get(t.id) || null, arms: t.arms.map((a) => ({ ...a, effects: withKept(a.effects), words: names.get(a.id) || null, next: copy(a.next) })) };
     };
     return {
       entry: s.entry,
@@ -970,7 +1046,7 @@ function buildWhatHappens(engine, { program, base = null, baseLabel = "base" } =
       transport: meta.transport || null,
       title: sc?.title || null,
       described: !!sc,
-      effects: s.effects,
+      effects: withKept(s.effects),
       tree: copy(s.tree),
       leafCount: Number(s.leafCount),
       truncated: s.truncated,
@@ -980,6 +1056,17 @@ function buildWhatHappens(engine, { program, base = null, baseLabel = "base" } =
       from: "structure.scenarios[]"
     };
   });
+  const shapeOf = (e) => {
+    const eff = (x) => `${x.op}${x.key ? `@${x.key.kind}` : ""}${x.value ? `<${x.value.kind}` : ""}${x.kept ? "|kept" : ""}`;
+    const go = (t) => !t ? "" : t.kind === "leaf" ? `(${t.outcome.kind}:${(t.outcome.statuses || (t.outcome.status ? [t.outcome.status] : [])).join("/")})` : `[${t.from.kind}${t.arms.map((a) => `{${a.effects.map(eff).join(",")}${go(a.next)}}`).join("")}]`;
+    return `${(e.effects || []).map(eff).join(",")}${go(e.tree)}`;
+  };
+  const byShape = /* @__PURE__ */ new Map();
+  for (const e of entries) byShape.set(shapeOf(e), [...byShape.get(shapeOf(e)) || [], e.entry]);
+  for (const e of entries) {
+    const same = byShape.get(shapeOf(e)).filter((x) => x !== e.entry);
+    if (same.length) e.sameShape = { entries: same, from: "derived: entries[] trees equal in node kinds, arms, effect verbs, row keys and value kinds, and outcomes" };
+  }
   const entryOf = new Map(entries.map((e) => [e.entry, e]));
   const leafById = new Map(entries.flatMap((e) => leavesOf(e.tree).map((l) => [l.id, l])));
   const checked = [], notes = [], refused = [], mismatches = [];
@@ -1085,6 +1172,18 @@ function buildWhatHappens(engine, { program, base = null, baseLabel = "base" } =
     refused,
     mismatches,
     diff,
+    // the comment above each definition, as its author wrote it (structure.docs); never checked
+    docs: ((callees) => Object.fromEntries(Object.entries(st.docs || {}).filter(([id]) => callees.has(id))))(
+      new Set(entries.flatMap((e) => {
+        const ids = [];
+        walk(e.tree, (n) => {
+          if (n.kind === "node" && n.from?.kind === "call") ids.push(n.from.callee);
+        });
+        return ids;
+      }))
+    ),
+    // what each table holds, by its checked row type (structure.rows)
+    rows: Object.fromEntries(Object.entries(st.rows || {}).map(([table, schema]) => [table, rowShape(schema)])),
     counts: {
       entries: entries.length,
       described: entries.length - ghosts.length,
@@ -1098,6 +1197,14 @@ function buildWhatHappens(engine, { program, base = null, baseLabel = "base" } =
     evidence: { tools: ["api_organize:structure", ...engine.access ? ["api_access_check"] : []], derived: ["diff: base red leaves matched by id, their failed obligations by identity"] }
   };
 }
+var typeName = (s) => s.type ? s.type.split("::").pop() : null;
+var fieldType = (s) => ({ string: "String", int: "Int", float64: "Float64", bool: "Bool", unit: "Unit", json: "Json" })[s.kind] || (s.kind === "list" ? `List[${fieldType(s.element)}]` : s.kind === "unsupported" ? s.rendered : s.kind === "union" && s.variants.length && s.variants.every((v) => !v.fields.length) ? s.variants.map((v) => v.tag).join(" | ") : typeName(s));
+function rowShape(s) {
+  if (s.kind === "list") return `List[${rowShape(s.element)}]`;
+  if (s.kind === "struct") return `${typeName(s)}(${s.fields.map((f) => `${f.name}: ${fieldType(f)}`).join(", ")})`;
+  if (s.kind === "union") return s.variants.map((v) => v.fields.length ? `${v.tag}(${v.fields.map((f) => `${f.name}: ${fieldType(f)}`).join(", ")})` : v.tag).join(" | ");
+  return fieldType(s);
+}
 function stationLabel(e) {
   const verb = e.op === "mint id" ? "mint" : e.op;
   if (e.tables.length) return `${verb} \xB7 ${e.tables.join(", ")}`;
@@ -2004,9 +2111,10 @@ async function direct({ root, engine, requirements, withMap = true, previous = n
       base.lawsError = checked.error;
       base.rules = (requirements.rules ?? []).map((r) => judgeRule(r, base.laws));
       base.hasActions = report.surface.routes.length > 0;
+      let access = null;
       if (base.hasActions || requirements.scenarios?.length) {
         try {
-          const access = await call(engine, "api_access_check", { sources });
+          access = await call(engine, "api_access_check", { sources });
           const record = WhatHappens.parse(buildWhatHappens({ structure: structureRaw, access }, { program: base.project }));
           base.whatHappens = base.hasActions ? record : { ...record, entries: [], ghosts: [], claims: [], witnesses: [], refused: [], notes: [] };
         } catch (error) {
@@ -2023,7 +2131,7 @@ async function direct({ root, engine, requirements, withMap = true, previous = n
               await call(engine, "api_organize", { sources, lens: "abstractions" }),
               await call(engine, "api_organize", { sources, lens: "layers" })
             ];
-            base.map = buildSystemMap({ report, structure: structureRaw, abstractions, layers }, { program: base.project });
+            base.map = buildSystemMap({ report, structure: structureRaw, abstractions, layers, ...access ? { access } : {} }, { program: base.project });
             base.layers = layers;
           } catch (error) {
             base.mapError = error instanceof Error ? error.message : String(error);
@@ -2419,7 +2527,8 @@ async function refresh() {
   const { state, requirements } = await (await fetch('/state')).json();
   const savedOf = id => requirements.answers.find(a => a.question === id);
   if (requirements.description) document.getElementById('description').textContent = requirements.description;
-  if (!state) return;
+  // Before the first check there is nothing drawn, but the person may already be looking.
+  if (!state) { viewing(null); return; }
   document.getElementById('project').textContent = ': ' + state.project;
   document.getElementById('updated').textContent = 'Last checked ' + new Date(state.updatedAt).toLocaleTimeString() + '.';
   document.getElementById('summary').textContent = state.summary;
@@ -2488,7 +2597,14 @@ var Report2 = z9.object({
   /** The drawing the anchors belong to (person.ts), or null before one is drawn. */
   drawing: z9.string().max(64).nullable()
 }).strict();
-var Viewing = Report2.extend({ schemaVersion: z9.literal("yichus-viewing-1"), at: z9.string() }).strict();
+var Viewing = Report2.extend({
+  schemaVersion: z9.literal("yichus-viewing-1"),
+  at: z9.string(),
+  /** The page server the report came through: only it can tell that its page went. */
+  server: z9.string().optional(),
+  /** When the last copy of the page open on that server went away, until a page connects again. */
+  closed: z9.string().optional()
+}).strict();
 var viewingPath = (root) => path5.join(studioDir(root), "viewing.json");
 function loadViewing(root) {
   const file = viewingPath(root);
@@ -2497,14 +2613,28 @@ function loadViewing(root) {
   if (!parsed.success) throw new Error(`${file} is not a yichus-viewing-1 file: ${z9.prettifyError(parsed.error)}`);
   return parsed.data;
 }
-function recordViewing(root, report, now) {
-  const parsed = Report2.safeParse(report);
-  if (!parsed.success) return { ok: false, error: `The page's report is not one this studio reads. ${z9.prettifyError(parsed.error)}` };
+function writeViewing(root, viewing) {
   ensureStudioDir(root);
   const file = viewingPath(root), written = `${file}.${process.pid}.tmp`;
-  fs5.writeFileSync(written, `${JSON.stringify(Viewing.parse({ schemaVersion: "yichus-viewing-1", at: now.toISOString(), ...parsed.data }), null, 2)}
+  fs5.writeFileSync(written, `${JSON.stringify(Viewing.parse(viewing), null, 2)}
 `);
   fs5.renameSync(written, file);
+}
+function recordClosed(root, server, now) {
+  const last = loadViewing(root);
+  if (last?.server === server) writeViewing(root, { ...last, closed: now.toISOString() });
+}
+function recordOpened(root, server) {
+  const last = loadViewing(root);
+  if (last?.server === server && last.closed) {
+    const { closed: _, ...open } = last;
+    writeViewing(root, open);
+  }
+}
+function recordViewing(root, server, report, now) {
+  const parsed = Report2.safeParse(report);
+  if (!parsed.success) return { ok: false, error: `The page's report is not one this studio reads. ${z9.prettifyError(parsed.error)}` };
+  writeViewing(root, { schemaVersion: "yichus-viewing-1", at: now.toISOString(), server, ...parsed.data });
   return { ok: true };
 }
 
@@ -2611,7 +2741,10 @@ function pageText(root, pageUrl, now, surface) {
 `;
 }
 function inViewLines(viewing, codeAt, said2, now, pageUrl) {
-  if (!viewing) return [`The page has not said what is on screen: it may not be open. ${pageUrl ? `Give the person its link: ${pageUrl}` : "The page is not running: start `yichus studio --page` in the background in this folder, then run this again for its link."}`];
+  const link = pageUrl ? `Give the person its link: ${pageUrl}` : "The page is not running: start `yichus studio --page` in the background in this folder, then run this again for its link.";
+  if (!viewing) return [`The page has not said what is on screen: it may not be open. ${link}`];
+  if (viewing.closed) return [`The person closed the page ${ago(viewing.closed, now)}, so it is not open now. ${pageUrl ? `If you want them to look at it, give them its link again: ${pageUrl}` : link}`];
+  if (!pageUrl) return [`The page is not open: its server stopped after it last said what was on screen. ${link}`];
   const parts = (anchors) => !viewing.current ? [] : anchors.flatMap((a) => codeAt.has(a) ? [`[${codeAt.get(a)}] ${said2.get(codeAt.get(a))}`] : []);
   const list = (what, items) => items.length ? [`${what}:`, ...items.map((i) => `  ${i}`)] : [];
   const { touched } = viewing;
@@ -2953,7 +3086,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.1" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+  const server = new Server({ name: "yichus-studio", version: "0.3.3" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
   const active = /* @__PURE__ */ new Set();
   const track = (task) => {
     active.add(task);
@@ -3222,7 +3355,7 @@ ${said2}
 var HELP = `yichus \u2014 the Yichus WebMCP analysis engine, locally
 
   yichus tools
-  yichus call TOOL [--args JSON_FILE|-] [--source FILE ... | --project DIR]
+  yichus call TOOL [--args JSON_FILE|-] [--arg-file NAME=JSON_FILE ...] [--source FILE ... | --project DIR]
   yichus verify FILE ... [--instances 1|many] [--block-on-warning ID ...]
   yichus lean FILE ... --lean-wasm-root DIRECTORY [--timeout-ms N]
 ${STUDIO_HELP}
@@ -3234,6 +3367,8 @@ Options:
                       (default the current folder), as the studio reads
                       it (call only).
   --args FILE|-       Tool arguments as a JSON object; - reads stdin.
+  --arg-file NAME=FILE  Set one argument to the JSON in FILE, such as a
+                      saved snapshot (repeatable; call only).
   --block-on-warning ID  A property id whose warning blocks the verdict, as a
                       violation would (repeatable; all names every property;
                       verify only). An id the verdict lacks exits 2.
@@ -3297,6 +3432,7 @@ var objectJson = (raw, label2) => objectValue(JSON.parse(raw), label2);
 var FLAGS = {
   source: { type: "string", multiple: true },
   args: { type: "string" },
+  "arg-file": { type: "string", multiple: true },
   project: { type: "string" },
   instances: { type: "string" },
   "block-on-warning": { type: "string", multiple: true },
@@ -3317,7 +3453,7 @@ function parse(argv2) {
   if (command !== "tools" && command !== "call" && command !== "verify" && command !== "lean") {
     throw new Error("Expected tools, call TOOL, verify FILE, or lean FILE; use --help for usage.");
   }
-  const opts = { command, sources: [], expects: [], blockOnWarnings: values["block-on-warning"] ?? [] };
+  const opts = { command, sources: [], argFiles: [], expects: [], blockOnWarnings: values["block-on-warning"] ?? [] };
   if (command === "call") {
     opts.tool = rest.shift();
     if (!opts.tool) throw new Error("call requires a tool name");
@@ -3325,6 +3461,14 @@ function parse(argv2) {
   if ((command === "tools" || command === "call") && rest.length) throw new Error(`Unexpected argument: ${rest[0]}`);
   opts.sources = [...rest, ...values.source ?? []];
   opts.args = values.args;
+  for (const value of values["arg-file"] ?? []) {
+    const equal = value.indexOf("=");
+    if (equal <= 0 || equal === value.length - 1) throw new Error("--arg-file requires NAME=FILE");
+    const name = value.slice(0, equal);
+    if (opts.argFiles.some((a) => a.name === name)) throw new Error(`--arg-file names ${name} twice`);
+    opts.argFiles.push({ name, file: value.slice(equal + 1) });
+  }
+  if (opts.argFiles.length && command !== "call") throw new Error("--arg-file is for call");
   opts.project = values.project;
   if (opts.project !== void 0 && command !== "call") throw new Error("--project is for call");
   if (opts.project !== void 0 && opts.sources.length) throw new Error("Use either --source files or --project, not both");
@@ -3430,6 +3574,15 @@ function sourceNames(paths) {
 }
 async function argumentsFor(opts, io) {
   const args = opts.args ? objectJson(opts.args === "-" ? await io.readStdin() : readInput(opts.args), "Arguments") : {};
+  for (const { name, file } of opts.argFiles) {
+    if (Object.hasOwn(args, name)) throw new Error(`Use either --arg-file ${name}=... or args.${name}, not both`);
+    try {
+      args[name] = JSON.parse(readInput(file));
+    } catch (error) {
+      if (error instanceof SyntaxError) throw new Error(`--arg-file ${name}: ${file} is not JSON (${error.message})`);
+      throw error;
+    }
+  }
   if (opts.sources.length) {
     if (Object.hasOwn(args, "sources")) throw new Error("Use either --source files or args.sources, not both");
     const names = sourceNames(opts.sources);
@@ -3457,7 +3610,7 @@ function clearOutput(opts) {
   if (!opts.output) return;
   const output = path9.resolve(opts.output);
   const outputStat = fs9.existsSync(output) ? fs9.statSync(output) : void 0;
-  for (const input of [...opts.sources, opts.args, opts.bundle].filter((p) => !!p && p !== "-")) {
+  for (const input of [...opts.sources, ...opts.argFiles.map((a) => a.file), opts.args, opts.bundle].filter((p) => !!p && p !== "-")) {
     const inputStat = fs9.existsSync(input) ? fs9.statSync(input) : void 0;
     if (path9.resolve(input) === output || outputStat && inputStat && inputStat.dev === outputStat.dev && inputStat.ino === outputStat.ino) {
       throw new Error("--output must not overwrite an input file");
@@ -3601,9 +3754,10 @@ async function startPageServer(root, assetsDir, port = null, now = () => /* @__P
   };
   for (const file of watched) fs10.watchFile(file, { interval: 250 }, changed);
   const hosts = /* @__PURE__ */ new Set();
+  let self = "", closing = false;
   const takes = /* @__PURE__ */ new Map([
     ["/answer", (args) => recordAnswer(root, args, now())],
-    ["/viewing", (args) => recordViewing(root, args, now())]
+    ["/viewing", (args) => recordViewing(root, self, args, now())]
   ]);
   const server = http.createServer((req, res) => {
     const send = (status, type, body) => {
@@ -3624,7 +3778,11 @@ async function startPageServer(root, assetsDir, port = null, now = () => /* @__P
       res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
       res.write(": connected\n\n");
       clients.add(res);
-      req.on("close", () => clients.delete(res));
+      recordOpened(root, self);
+      req.on("close", () => {
+        clients.delete(res);
+        if (!clients.size && !closing) recordClosed(root, self, now());
+      });
       return;
     }
     const asset = PAGE_ASSETS.find((a) => url.pathname === `/${a}`);
@@ -3667,9 +3825,11 @@ async function startPageServer(root, assetsDir, port = null, now = () => /* @__P
   }
   const bound = server.address().port;
   hosts.add(`127.0.0.1:${bound}`).add(`localhost:${bound}`);
+  self = `http://127.0.0.1:${bound}/`;
   return {
-    url: `http://127.0.0.1:${bound}/`,
+    url: self,
     async close() {
+      closing = true;
       for (const file of watched) fs10.unwatchFile(file, changed);
       const closed = new Promise((resolve) => server.close(() => resolve()));
       server.closeAllConnections();