cortad 0.2.2 → 0.3.0-rc.10

package/lib/pyhook/sitecustomize.py

@@ -7,6 +7,7 @@
 import os
 
 _FILE = os.environ.get("CORTAD_TRACE_FILE")
+_RULES = os.environ.get("CORTAD_RULES_FILE")
 
 
 def _install():
@@ -25,6 +26,159 @@ def _install():
     model_host = re.compile(r"(?:^|\.)(?:openai\.com|anthropic\.com|fireworks\.ai|openrouter\.ai|groq\.com|mistral\.ai|together\.xyz|together\.ai|deepseek\.com|cohere\.ai|cohere\.com|perplexity\.ai|x\.ai|openai\.azure\.com|cognitiveservices\.azure\.com|replicate\.com|huggingface\.co|cerebras\.ai|deepinfra\.com|novita\.ai|moonshot\.cn|dashscope\.aliyuncs\.com|bigmodel\.cn|ai-gateway\.vercel\.sh|gateway\.ai\.cloudflare\.com|helicone\.ai|portkey\.ai)$", re.I)
     model_path = re.compile(r"/(?:chat/completions|completions|responses|messages|embeddings)$|:(?:generateContent|streamGenerateContent)|/invoke(?:-with-response-stream)?$|/api/(?:chat|generate)$", re.I)
 
+    # The turn a message came in under, when the run tagged it (one opaque id per request), so a
+    # model call and its prompt can be pinned to the reply they produced while turns overlap.
+    turn_ok = re.compile(r"^[A-Za-z0-9:_.-]{1,80}$")
+
+    def turn_now():
+        req = ctx.get()
+        return req.get("turn") if req else None
+
+    # The customer's own rule sentences, written beside the trace by the run, so each model call can
+    # say which of them its prompt carried. Absent file, nothing is claimed. Reloaded on change.
+    rules_at = [-1.0]
+    rules = [None]
+    slot = re.compile(r"\{[^}]*\}|\$\{[^}]*\}|%[sd]|<[^>]{1,40}>")
+
+    def norm(s):
+        s = str(s or "")
+        s = re.sub(r"\\u([0-9a-fA-F]{4})", lambda m: chr(int(m.group(1), 16)), s)
+        s = re.sub(r"\\[nrt]", " ", s).replace('\\"', '"').replace("\\\\", "\\")
+        return re.sub(r"\s+", " ", s.lower()).strip()
+
+    def rules_now():
+        if not _RULES:
+            return None
+        try:
+            at = os.stat(_RULES).st_mtime
+            if at != rules_at[0]:
+                rules_at[0] = at
+                with open(_RULES, encoding="utf-8") as f:
+                    raw = json.load(f)
+                out = []
+                for r in raw if isinstance(raw, list) else []:
+                    if not isinstance(r, dict) or not isinstance(r.get("id"), str) or not isinstance(r.get("text"), str):
+                        continue
+                    parts = [p for p in (norm(x) for x in slot.split(r["text"])) if len(p) >= 12]
+                    if parts:
+                        out.append((r["id"], parts))
+                rules[0] = out
+        except Exception:
+            pass
+        return rules[0]
+
+    # What the app's tools answered, as the prompt of the next model call carries them (chat tool
+    # messages, responses function outputs, Anthropic tool_result blocks, Gemini functionResponse
+    # parts): the material a reply's facts rest on. Bounded per call.
+    tool_text, tools_max = 3000, 12
+
+    def text_of(v):
+        if isinstance(v, str):
+            return v
+        if isinstance(v, list):
+            return "\n".join(p for p in ((x.get("text") or x.get("content") or "") if isinstance(x, dict) else str(x or "") for x in v) if p)
+        if isinstance(v, dict):
+            try:
+                return json.dumps(v, ensure_ascii=False)
+            except (TypeError, ValueError):
+                return ""
+        return ""
+
+    def tools_in(sent):
+        body = parsed(sent) if isinstance(sent, str) else None
+        if not isinstance(body, dict):
+            return None
+        out, names = [], {}
+
+        def add(name, text):
+            t = text_of(text)[:tool_text]
+            if t.strip() and len(out) < tools_max and all(o["text"] != t for o in out):
+                out.append({"name": str(name or "")[:80], "text": t})
+
+        messages = body.get("messages") if isinstance(body.get("messages"), list) else []
+        for m in messages:
+            if not isinstance(m, dict):
+                continue
+            for c in m.get("tool_calls") or []:
+                if isinstance(c, dict) and c.get("id") and isinstance(c.get("function"), dict):
+                    names[c["id"]] = c["function"].get("name")
+            if isinstance(m.get("content"), list):
+                for c in m["content"]:
+                    if isinstance(c, dict) and c.get("type") == "tool_use" and c.get("id"):
+                        names[c["id"]] = c.get("name")
+        for m in messages:
+            if not isinstance(m, dict):
+                continue
+            if m.get("role") in ("tool", "function"):
+                add(m.get("name") or names.get(m.get("tool_call_id")), m.get("content"))
+            if isinstance(m.get("content"), list):
+                for c in m["content"]:
+                    if isinstance(c, dict) and c.get("type") == "tool_result":
+                        add(names.get(c.get("tool_use_id")), c.get("content"))
+        items = body.get("input") if isinstance(body.get("input"), list) else []
+        for it in items:
+            if isinstance(it, dict) and it.get("type") == "function_call" and it.get("call_id"):
+                names[it["call_id"]] = it.get("name")
+        for it in items:
+            if isinstance(it, dict) and it.get("type") == "function_call_output":
+                add(names.get(it.get("call_id")), it.get("output"))
+        for c in body.get("contents") if isinstance(body.get("contents"), list) else []:
+            for p in c.get("parts") if isinstance(c, dict) and isinstance(c.get("parts"), list) else []:
+                if isinstance(p, dict) and isinstance(p.get("functionResponse"), dict):
+                    add(p["functionResponse"].get("name"), p["functionResponse"].get("response"))
+        return out or None
+
+    # A framework that folds its tools' answers into the next prompt as plain text sends no tool
+    # message to find: within one turn, what a later call's prompt carries that the call before did
+    # not, outside the model's own words, is that material. The first call holds the customer's
+    # message and the system prompt, present in every later call, so neither is ever counted.
+    seen_by_turn = {}
+
+    def texts_of(body):
+        out = set()
+
+        def take(v):
+            t = text_of(v).strip()
+            if t:
+                out.add(t[:tool_text])
+        for m in body.get("messages") if isinstance(body.get("messages"), list) else []:
+            if isinstance(m, dict) and m.get("role") != "assistant":
+                take(m.get("content"))
+        for it in body.get("input") if isinstance(body.get("input"), list) else []:
+            if isinstance(it, dict) and it.get("role") != "assistant" and it.get("type") != "function_call":
+                take(it.get("content") if it.get("content") is not None else it.get("output"))
+        if isinstance(body.get("system"), str):
+            take(body["system"])
+        for c in body.get("contents") if isinstance(body.get("contents"), list) else []:
+            if isinstance(c, dict) and c.get("role") != "model":
+                for p in c.get("parts") if isinstance(c.get("parts"), list) else []:
+                    if isinstance(p, dict) and isinstance(p.get("text"), str):
+                        take(p["text"])
+        return out
+
+    def material_in(sent, turn):
+        if not turn:
+            return None
+        body = parsed(sent) if isinstance(sent, str) else None
+        if not isinstance(body, dict):
+            return None
+        now = texts_of(body)
+        before = seen_by_turn.get(turn)
+        seen_by_turn[turn] = now
+        if len(seen_by_turn) > 200:
+            seen_by_turn.pop(next(iter(seen_by_turn)))
+        if before is None:
+            return None
+        fresh = [{"name": "", "text": t} for t in now if t not in before][:tools_max]
+        return fresh or None
+
+    def rules_in(sent):
+        found = rules_now()
+        if found is None:
+            return None
+        body = norm(sent)
+        return [rid for rid, parts in found if all(p in body for p in parts)]
+
     def write(row):
         try:
             fd = os.open(_FILE, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
@@ -33,6 +187,17 @@ def _install():
         except OSError:
             pass
 
+    # Every other outbound call: the host and what it answered, never a byte of it. A search
+    # provider over its limit for a whole run was invisible until this row existed.
+    def dep(url, status, code=None):
+        try:
+            host = (urlsplit(str(url)).hostname or "").lower()
+            if not host or host in ("localhost", "127.0.0.1", "::1"):
+                return
+            turn = turn_now()
+            write({"dep": {"at": int(time.time() * 1000), "host": host[:253], "status": int(status or 0), **({"code": str(code)[:40]} if code else {}), **({"turn": turn} if turn else {})}})
+        except Exception:
+            pass
     def is_model_call(url):
         try:
             parts = urlsplit(str(url))
@@ -141,19 +306,31 @@ def _install():
         except Exception:
             return ""
 
-    def meter(url, sent, status, kind, raw):
+    def meter(url, sent, status, kind, raw, turn=None):
         try:
             tokens, model = read_reply(kind, (raw or "")[:reply_max])
             parts = urlsplit(str(url))
             row = {"at": int(time.time() * 1000), "host": parts.netloc.replace(":443", ""), "model": str(asked_for(url, sent) or model or "")[:160],
                    "status": int(status or 0), "usage": tokens is not None}
             row.update(tokens or {"promptTokens": 0, "cachedTokens": 0, "completionTokens": 0})
+            turn = turn or turn_now()
+            if turn:
+                row["turn"] = turn
+            as_text = sent if isinstance(sent, str) else text(sent)
+            found = rules_in(as_text)
+            if found is not None:
+                row["rules"] = found
+            tools = tools_in(as_text) or material_in(as_text, turn)
+            if tools:
+                row["tools"] = tools
             write({"call": row})
         except Exception:
             pass
 
     def started(method, path, headers):
-        return {"method": method, "path": path, "headers": headers, "chunks": [], "size": 0, "noted": False}
+        turn = headers.pop("x-cortad-turn", None)
+        return {"method": method, "path": path, "headers": headers, "chunks": [], "size": 0, "noted": False,
+                "turn": turn if isinstance(turn, str) and turn_ok.match(turn) else None}
 
     def keep(req, chunk):
         if chunk and req["size"] < limit:
@@ -249,16 +426,154 @@ def _install():
         wrapped._brainsless = True
         return wrapped
 
+    # The app's own route table, read off the app object the server was handed, so the run knows
+    # every door the app has before a message is sent. Read only: nothing here changes the app.
+    route_max, openapi_max = 400, 8 * 1024 * 1024
+    verbs = ("GET", "POST", "PUT", "PATCH", "DELETE")
+    served_port = [None]
+
+    def template(path):
+        # One syntax for every framework's path parameters: OpenAPI's {name}.
+        p = re.sub(r"\(\?P<(\w+)>(?:[^()]|\([^()]*\))*\)", r"{\1}", str(path))
+        p = re.sub(r"<(?:[^<>:]+:)?(\w+)>", r"{\1}", p)
+        p = re.sub(r"\{(\w+):[^{}]*\}", r"{\1}", p)
+        p = re.sub(r"(?:\$|\\Z)$", "", re.sub(r"^\^", "", p))
+        return p.replace("\\.", ".").replace("/?", "/")
+
+    def source_of(fn):
+        import inspect
+        try:
+            fn = inspect.unwrap(fn)
+        except Exception:
+            pass
+        code = getattr(fn, "__code__", None)
+        path = code.co_filename if code else getattr(sys.modules.get(getattr(fn, "__module__", None) or ""), "__file__", None) or ""
+        rel = os.path.relpath(path, os.getcwd()) if path else ""
+        theirs = rel and not rel.startswith("..") and "site-packages" not in rel and "dist-packages" not in rel
+        return (rel if theirs else ""), str(getattr(fn, "__name__", "") or "")
+
+    def add(out, methods, path, fn):
+        # Methods unknown: the two a door is asked with.
+        file, handler = source_of(fn) if fn is not None else ("", "")
+        for m in ("POST", "GET") if methods is None else methods:
+            m = str(m).upper()
+            if m not in ("HEAD", "OPTIONS") and len(out) < route_max:
+                out.append({"method": m, "path": ("/" + template(path).lstrip("/"))[:1024], "file": file[:512], "handler": handler[:200]})
+
+    def class_methods(cls):
+        return [m for m in verbs if callable(getattr(cls, m.lower(), None))]
+
+    def starlette_routes(routes, prefix, out):
+        for r in routes or []:
+            path = prefix + (getattr(r, "path", "") or "")
+            sub = getattr(r, "routes", None)
+            # FastAPI 0.14x keeps an included router whole and resolves its routes on demand.
+            if callable(getattr(r, "effective_route_contexts", None)):
+                for c in r.effective_route_contexts():
+                    if c.starlette_route is not None:
+                        starlette_routes([c.starlette_route], prefix, out)
+                    else:
+                        add(out, c.methods, prefix + c.path, c.endpoint)
+            elif sub is not None:
+                starlette_routes(sub, path, out)
+            elif getattr(r, "endpoint", None) is not None and "WebSocket" not in type(r).__name__:
+                fn = r.endpoint
+                add(out, getattr(r, "methods", None) or (class_methods(fn) if isinstance(fn, type) else None), path, fn)
+
+    def flask_routes(app, out):
+        for rule in app.url_map.iter_rules():
+            if rule.endpoint != "static" and not rule.endpoint.endswith(".static"):
+                add(out, rule.methods, rule.rule, app.view_functions.get(rule.endpoint))
+
+    def django_routes(_app, out):
+        from django.urls import URLResolver, get_resolver
+
+        def walk(patterns, prefix):
+            for p in patterns:
+                path = prefix + template(str(p.pattern))
+                if isinstance(p, URLResolver):
+                    walk(p.url_patterns, path)
+                    continue
+                cb = p.callback
+                actions = getattr(cb, "actions", None)
+                cls = getattr(cb, "cls", None) or getattr(cb, "view_class", None)
+                add(out, list(actions) if isinstance(actions, dict) else class_methods(cls) if cls else None, path, cls or cb)
+
+        walk(get_resolver().url_patterns, "/")
+
+    def litestar_routes(app, out):
+        for r in app.routes:
+            for h in getattr(r, "route_handlers", None) or []:
+                methods = [m for m in getattr(h, "http_methods", ()) if str(m).upper() in verbs]
+                if methods:
+                    add(out, methods, r.path, getattr(h, "fn", None))
+
+    def aiohttp_routes(app, out):
+        for r in app.router.routes():
+            add(out, None if r.method == "*" else [r.method], r.resource.canonical if r.resource else "", r.handler)
+
+    def asgi_routes(app, out):
+        starlette_routes(app.routes, "", out)
+
+    walkers = (("fastapi", "routes", asgi_routes), ("starlette", "routes", asgi_routes),
+               ("quart", "url_map", flask_routes), ("flask", "url_map", flask_routes),
+               ("litestar", "routes", litestar_routes), ("aiohttp", "router", aiohttp_routes),
+               ("django", None, django_routes))
+
+    def app_in(obj):
+        # Servers hand the app over inside their own middleware, and each layer keeps the next.
+        for _ in range(12):
+            if obj is None:
+                break
+            tops = {c.__module__.split(".")[0] for c in type(obj).__mro__}
+            for name, attr, walk in walkers:
+                if name in tops and (attr is None or hasattr(obj, attr)):
+                    return name, obj, walk
+            inner = getattr(obj, "app", None)
+            obj = inner if inner is not None else getattr(obj, "application", None)
+        return None, None, None
+
+    def openapi_of(name, app):
+        try:
+            if name == "fastapi":
+                # openapi() caches what it builds; the app's own cache is put back as it was.
+                kept = app.openapi_schema
+                try:
+                    doc = app.openapi()
+                finally:
+                    app.openapi_schema = kept
+            elif name == "litestar":
+                doc = app.openapi_schema.to_schema()
+            else:
+                return None
+            return doc if isinstance(doc, dict) and len(json.dumps(doc)) <= openapi_max else None
+        except Exception:
+            return None
+
+    def publish_routes(app, port):
+        name, found, out = None, None, []
+        try:
+            name, found, walk = app_in(app)
+            if walk:
+                walk(found, out)
+        except Exception:
+            pass
+        port = port if isinstance(port, int) and not isinstance(port, bool) else None
+        write({"routes": {"framework": name or "unknown", "port": port, "routes": out, "openapi": openapi_of(name, found)}})
+
     # What is patched, once the module it lives in has been imported by the app itself.
     def patch_uvicorn(module):
         load = module.Config.load
 
         def loaded(self, *a, **k):
             out = load(self, *a, **k)
+            # Under gunicorn, uvicorn's own port is its default and the socket is gunicorn's.
+            port = served_port[0] or getattr(self, "port", None)
+            publish_routes(self.loaded_app, port)
             if not isinstance(self.loaded_app, Asgi):
                 self.loaded_app = Asgi(self.loaded_app)
-            if isinstance(getattr(self, "port", None), int):
-                write({"listen": self.port, "pid": os.getpid()})
+            if isinstance(port, int):
+                write({"listen": port, "pid": os.getpid()})
             return out
 
         module.Config.load = loaded
@@ -269,6 +584,7 @@ def _install():
         def run(hostname, port, application, *a, **k):
             if isinstance(port, int):
                 write({"listen": port, "pid": os.getpid()})
+            publish_routes(application, port)
             return run_simple(hostname, port, wsgi(application), *a, **k)
 
         module.run_simple = run
@@ -281,6 +597,54 @@ def _install():
 
         module.WSGIHandler.__call__ = called
 
+    def patch_django_server(module):
+        run = module.run
+
+        def running(addr, port, wsgi_handler, *a, **k):
+            publish_routes(wsgi_handler, port)
+            return run(addr, port, wsgi_handler, *a, **k)
+
+        module.run = running
+
+    def patch_gunicorn(module):
+        load = module.Worker.load_wsgi
+
+        def loaded(self):
+            out = load(self)
+            try:
+                bound = [s.getsockname() for s in self.sockets]
+                served_port[0] = next((at[1] for at in bound if isinstance(at, tuple)), None)
+            except Exception:
+                pass
+            publish_routes(self.wsgi, served_port[0])
+            return out
+
+        module.Worker.load_wsgi = loaded
+
+    def patch_hypercorn(module):
+        serve = module.worker_serve
+
+        def serving(app, config, *a, **k):
+            port = None
+            try:
+                port = int(str(config.bind[0]).rsplit(":", 1)[1])
+            except Exception:
+                pass
+            publish_routes(app, port)
+            return serve(app, config, *a, **k)
+
+        module.worker_serve = serving
+
+    def patch_aiohttp_web(module):
+        run_app = module.run_app
+
+        def run(app, *a, **k):
+            if isinstance(app, module.Application):
+                publish_routes(app, k.get("port") or 8080)
+            return run_app(app, *a, **k)
+
+        module.run_app = run
+
     def sent_of(request):
         try:
             return text(request.content)
@@ -330,6 +694,7 @@ def _install():
 
         def watch(request, response, sent):
             if not is_model_call(request.url):
+                dep(request.url, response.status_code)
                 return response
             kind = response.headers.get("content-type", "")
             if getattr(response, "_content", None) is not None:
@@ -356,9 +721,11 @@ def _install():
                         pass
                     try:
                         response = _send(self, request, *a, **k)
-                    except Exception:
+                    except Exception as err:
                         if is_model_call(request.url):
                             meter(request.url, sent, 0, "", "")
+                        else:
+                            dep(request.url, 0, type(err).__name__)
                         raise
                     try:
                         return watch(request, response, sent)
@@ -374,9 +741,11 @@ def _install():
                         pass
                     try:
                         response = await _send(self, request, *a, **k)
-                    except Exception:
+                    except Exception as err:
                         if is_model_call(request.url):
                             meter(request.url, sent, 0, "", "")
+                        else:
+                            dep(request.url, 0, type(err).__name__)
                         raise
                     try:
                         return watch(request, response, sent)
@@ -392,8 +761,15 @@ def _install():
                 note(request.url, request.body)
             except Exception:
                 pass
-            response = send(self, request, *a, **k)
             try:
+                response = send(self, request, *a, **k)
+            except Exception as err:
+                if not is_model_call(request.url):
+                    dep(request.url, 0, type(err).__name__)
+                raise
+            try:
+                if not is_model_call(request.url):
+                    dep(request.url, response.status_code)
                 if is_model_call(request.url):
                     # A streamed reply is counted as a call whose counts were not read.
                     raw = response.content.decode("utf-8", "replace") if getattr(response, "_content_consumed", False) else ""
@@ -413,9 +789,16 @@ def _install():
                 note(str_or_url, body)
             except Exception:
                 pass
-            response = await request(self, method, str_or_url, *a, **k)
+            try:
+                response = await request(self, method, str_or_url, *a, **k)
+            except Exception as err:
+                if not is_model_call(str_or_url):
+                    dep(str_or_url, 0, type(err).__name__)
+                raise
             if is_model_call(str_or_url):
-                response._cortad = (str_or_url, text(body))
+                response._cortad = (str_or_url, text(body), turn_now())
+            else:
+                dep(str_or_url, response.status)
             return response
 
         # Metered when your app reads the reply, or, for one it streams, when the reply is let go.
@@ -426,14 +809,14 @@ def _install():
             call = getattr(self, "_cortad", None)
             if call:
                 self._cortad = None
-                meter(call[0], call[1], self.status, self.headers.get("content-type", ""), (raw or b"").decode("utf-8", "replace"))
+                meter(call[0], call[1], self.status, self.headers.get("content-type", ""), (raw or b"").decode("utf-8", "replace"), call[2])
             return raw
 
         def release_kept(self, *a, **k):
             call = getattr(self, "_cortad", None)
             if call:
                 self._cortad = None
-                meter(call[0], call[1], self.status, self.headers.get("content-type", ""), "")
+                meter(call[0], call[1], self.status, self.headers.get("content-type", ""), "", call[2])
             return release(self, *a, **k)
 
         module.ClientSession._request = requested
@@ -441,6 +824,8 @@ def _install():
         module.ClientResponse.release = release_kept
 
     exact = {"uvicorn.config": patch_uvicorn, "werkzeug.serving": patch_werkzeug, "django.core.handlers.wsgi": patch_django,
+             "django.core.servers.basehttp": patch_django_server, "gunicorn.workers.base": patch_gunicorn,
+             "hypercorn.asyncio.run": patch_hypercorn, "hypercorn.trio.run": patch_hypercorn, "aiohttp.web": patch_aiohttp_web,
              "requests.sessions": patch_requests, "aiohttp.client": patch_aiohttp}
     # By family, not by name: the OpenAI SDK moved to a renamed copy of httpx (httpx2), and a patch
     # keyed on "httpx" alone saw none of its calls.

package/lib/read-text.mjs

@@ -0,0 +1,91 @@
+import { at, clip, has, num, pack, pageOf, plural, SIDE } from "./words.mjs";
+
+// What Cortad read of the repository: the walkthrough `status` carries, and one section in full
+// for `status` with show. Both use the same lines, so the full list reads like the walkthrough.
+//
+// The full list comes back from GET /mcp/status?show=<name>: read.rules.all, read.machine.misses
+// complete with read.machine.mets, read.journeys.all, read.doors.all, read.trials.all. Where the API
+// has not sent it, what it did send is listed with "n of N listed".
+export const SHOW = ["rules", "standards", "journeys", "endpoints", "trials"];
+
+const rulesHead = (rules) => {
+  const files = Array.isArray(rules.files) ? rules.files.length : rules.files;
+  return `Rules in the code: ${num(rules.count)}${has(files) ? `, in ${plural(files, "file")}` : ""}.`;
+};
+const ruleLine = (e) => `  ${at(e.path, e.line)}  "${clip(e.text, 300)}"`;
+const headOf = (label, parts) => (parts.some(Boolean) ? `${label}: ${parts.filter(Boolean).join(", ")}.` : `${label}:`);
+const standardsHead = (m) => headOf("Engineering standards", [has(m.decided) && `${num(m.decided)} decided`, has(m.met) && `${num(m.met)} met`, has(m.missed) && `${num(m.missed)} missed`]);
+const standardLine = (x) => `  ${x.path ? `${at(x.path, x.line)}  ` : ""}${x.standard}${x.detail ? `: ${clip(x.detail, 240)}` : ""}${x.decidedBy ? ` (decided by ${x.decidedBy === "code" ? "code" : "a model"})` : ""}`;
+const trialsHead = (t) => headOf("Trials", [has(t.written) && `${num(t.written)} written`, has(t.playable) && `${num(t.playable)} playable`]);
+const heldWhy = (h) => `${SIDE[h.side] ? `, ${SIDE[h.side]}` : ""}${h.why ? `: ${clip(h.why, 300)}` : ""}`;
+const named = (label, group, max = 12) => {
+  if (!group) return null;
+  const names = group.names ?? [];
+  const more = (group.count ?? names.length) - Math.min(names.length, max);
+  const list = names.slice(0, max).join(", ");
+  return `${label} (${num(group.count ?? names.length)})${list ? `: ${list}${more > 0 ? `, and ${more} more` : ""}` : ""}.`;
+};
+// "Journeys (6):" when every one is here, "Journeys (6), 4 listed:" when not.
+const counted = (label, count, n) => `${label} (${num(count ?? n)})${has(count) && n < count ? `, ${num(n)} listed` : ""}:`;
+
+// The walkthrough, in the order the person is walked through it.
+export function readLines(r) {
+  const lines = ["What Cortad read:"];
+  if (r.rules) {
+    const examples = (r.rules.examples ?? []).slice(0, 3);
+    lines.push(`${rulesHead(r.rules)}${examples.length ? ` ${examples.length} of them:` : ""}`, ...examples.map(ruleLine));
+  }
+  for (const line of [named("Journeys", r.journeys), named("Simulated users", r.profiles), named("Endpoints", r.doors)]) if (line) lines.push(line);
+  const m = r.machine;
+  if (m) {
+    const misses = m.misses ?? [];
+    lines.push(standardsHead(m), ...misses.slice(0, 12).map(standardLine));
+    if (misses.length > 12) lines.push(`  and ${misses.length - 12} more.`);
+  }
+  const q = r.questions;
+  if (q) lines.push(`Questions: ${num(q.total)}${has(q.everywhere) ? `; ${num(q.everywhere)} asked in every conversation` : ""}${has(q.placed) ? `, ${num(q.placed)} placed in the situations they fit` : ""}.`);
+  const t = r.trials;
+  if (t) lines.push(trialsHead(t), ...(t.held ?? []).map((h) => `  ${h.surface}: ${plural(h.n, "trial")} held back${heldWhy(h)}`));
+  return lines;
+}
+
+export function showText(d, show, page = 1) {
+  if (!d.read) return "Cortad is still reading this repository.";
+  const { head, lines, continued } = sectionOf(d.read, show);
+  return pageOf(pack(head, lines, continued), page, (n) => `status with show ${show} and page ${n}`);
+}
+
+function sectionOf(r, show) {
+  switch (show) {
+    case "rules": {
+      const rules = r.rules ?? { count: 0 };
+      const all = rules.all ?? rules.examples ?? [];
+      return { head: `${rulesHead(rules)}${all.length < rules.count ? ` ${num(all.length)} of ${num(rules.count)} listed.` : ""}`, lines: all.map(ruleLine), continued: "Rules in the code, continued." };
+    }
+    case "standards": {
+      const m = r.machine ?? {};
+      const misses = m.misses ?? [];
+      const mets = m.mets ?? [];
+      return {
+        head: standardsHead(m),
+        lines: [misses.length && counted("Missed", m.missed, misses.length), ...misses.map(standardLine), mets.length && counted("Met", m.met, mets.length), ...mets.map(standardLine)].filter(Boolean),
+        continued: "Engineering standards, continued.",
+      };
+    }
+    case "journeys": {
+      const all = r.journeys?.all ?? (r.journeys?.names ?? []).map((name) => ({ name }));
+      return { head: counted("Journeys", r.journeys?.count, all.length), lines: all.map((j) => `  ${j.name}${j.steps?.length ? `: ${clip(j.steps.join("; "), 600)}` : ""}`), continued: "Journeys, continued." };
+    }
+    case "endpoints": {
+      const all = r.doors?.all ?? (r.doors?.names ?? []).map((name) => ({ name }));
+      return { head: counted("Endpoints", r.doors?.count, all.length), lines: all.map((e) => `  ${e.name}${e.path ? `: ${[e.method, e.path].filter(Boolean).join(" ")}` : ""}`), continued: "Endpoints, continued." };
+    }
+    case "trials":
+    default: {
+      const t = r.trials ?? {};
+      const all = t.all ?? (t.held ?? []).map((h) => ({ surface: h.surface, held: h.n, why: h.why, side: h.side }));
+      const line = (x) => `  ${x.surface}: ${[has(x.written) && `${num(x.written)} written`, has(x.playable) && `${num(x.playable)} playable`, x.held && `${num(x.held)} held back`].filter(Boolean).join(", ")}${x.held ? heldWhy(x) : ""}`;
+      return { head: trialsHead(t), lines: all.map(line), continued: "Trials, continued." };
+    }
+  }
+}