volaro 0.1.0-alpha.3 → 0.1.0-alpha.4

package/README.md

@@ -1,6 +1,6 @@
 # Volaro
 
-**Limited alpha, published as `0.1.0-alpha.1` under the `alpha` dist-tag** —
+**Limited alpha, published under the `alpha` dist-tag** (this is `0.1.0-alpha.4`) —
 `npm install volaro@alpha`. Not `latest` (that still resolves to an earlier
 `0.0.x` placeholder) — always specify `@alpha` or the exact version.
 
@@ -59,9 +59,56 @@ volaro example sensors   # a worked example (also: station)
 volaro version | volaro help
 ```
 
+### Benchmark timing log
+
+`check` and `build` can append machine-readable compile attempts to a JSONL
+file. Use one unique run ID for the first attempt and every repair attempt in a
+single trial:
+
+```bash
+volaro check app.vl --benchmark-log benchmark.jsonl --benchmark-run test-006-v-01
+# If it fails, repair app.vl and repeat the exact command with the same run ID.
+```
+
+A first-pass success writes a `clean` summary with `t_clean_ms`. A failure
+followed by a success writes a `recovered` summary with `t_fail_ms`,
+`t_repair_ms`, `t_recompile_ms`, and `t_recover_ms`. The log also retains every
+raw attempt, the number of failures, and compiler overhead not attributable to
+repair. A completed run ID cannot be reused, and a run cannot mix `check` and
+`build` attempts or change compiler arguments between attempts.
+
+The timer measures the compiler subprocess. `T-repair` is the observed wall
+time between a failed compiler exit and the next compiler start. It measures
+the autonomous repair loop, including agent and tool overhead; it is not a
+claim about model-inference time alone.
+
+**Every failed attempt is classified, not just counted.** Each raw `attempt`
+record carries a `classification`: `source_diagnostic` (the compiler ran to
+completion and correctly reported a problem with your source — the only case
+`t_fail_ms` is ever populated for), `operational_failure` (the compiler process
+itself crashed, was killed, or stopped on an invocation/configuration problem —
+`crash_exception_type`/`crash_exception_message` are set when it was a crash),
+`silent_failure` (a non-zero exit with no output at all), or `unknown_failure`
+(a non-zero exit with output that carried none of the compiler's own
+diagnostic signal). This is reported by the compiler itself over a private
+side channel — never guessed from whether stdout/stderr happened to have
+anything in it, since an internal crash prints output too. A `recovered`
+summary whose original failing attempt was not `source_diagnostic` has
+`t_fail_ms: null`, `timing_complete: false`, and a `timing_incomplete_reason`
+explaining why — treat it as an invalid recovery-time sample, not a slow one.
+
+**A `recovered` summary can also be invalidated by the wall clock.**
+`t_repair_ms`/`t_recover_ms` are computed from separate processes' own
+timestamps; if one of those timestamps predates an earlier one (a system
+clock step between two attempts), the summary has `clock_anomaly: true`,
+`timing_complete: false`, and the affected fields are `null` — never a
+clamped, misleadingly small positive number.
+
 `volaro dev` serves a static bundle for a single-page app. If the app compiles
 to a full-stack server (`server.js`), it runs that instead and needs
-Node 22.5+ for `node:sqlite`.
+Node 22.5+ for `node:sqlite`. A multi-page project build always emits a
+`server.js` (it serves `public/` and answers a direct link or refresh on a
+dynamic route), so `volaro dev` on a project directory runs that server.
 
 ## Scaffold a project
 
@@ -82,8 +129,20 @@ density against selected baselines — not a general productivity result.
 Security and accessibility checks cover a tested prototype subset, not a
 universal guarantee. Independent human-readability validation is outstanding.
 
-**MVP scope is single-page.** Routing, nested layouts and multi-page starters
-are later work; `volaro build` / `volaro dev` target one entry file.
+**Pages, routing and nested layouts are implemented** (2026-09-23). A project
+directory with any `app/**/index.vl` builds as a real multi-page app: nested
+`_layout.vl` shells placing content with `@children`, `(group)` folders that add
+layout ancestry but no URL segment, typed `[name=type]` dynamic parameters, and
+optional `_loading.vl` / `_error.vl` / `_not-found.vl` boundaries, served by a
+client router with a direct-link/refresh fallback in the generated server. Point
+`volaro build` / `volaro dev` at the project directory; `volaro routes` prints
+what was discovered. A single `.vl` entry file still builds exactly as before.
+
+**Still out of scope:** server-side rendering and hydration (the shell is
+route-agnostic and the client does the first render); `theme` / `recipe` styling
+in a multi-page build, so styled output is single-entry only; catch-all routes,
+per-file route prefixes, and inherited authorization. **`npm create volaro`
+scaffolds a single-page starter** — a multi-page starter is later work.
 
 ## Not included
 
@@ -93,9 +152,12 @@ builds (`theme` / `recipe`) additionally need a one-time
 `npm ci` inside `compiler/vlbuild/styling`; the single-page starter does not
 use them.
 
-**Form controls:** the element set is `text` inputs plus `button` / `link` —
-there is no `checkbox`, `radio`, `select`, `textarea`, or `disabled` attribute.
-Model a toggle as a `button` reading a `state` bool. `variant:` is a literal
+**Form controls:** `input` (a full type matrix, including `checkbox`/`radio`
+binding a `checked` state), `textarea`, `select`/`option`/`optgroup`,
+`fieldset`/`legend`, `datalist`, `button`, `link`. `disabled:` works on
+`button input textarea select fieldset optgroup option`. There is no
+standalone `label` element and no semantic `switch`/`aria-pressed` toggle —
+model one as a `button` reading a `state` bool. `variant:` is a literal
 style name, not a computed expression. `if` used as an expression is binary
 (`if c a else b`); `match` and block `if` are statements only. A module-level
 `fn` is not available to a view. **`volaro supported` and `volaro crib` are

package/bin/vl.js

@@ -5,6 +5,7 @@
 //   volaro check <path>...        validate .vl source (lexer / parser / resolver)
 //   volaro build <file.vl>        transpile to a runnable bundle
 //   volaro dev [file.vl]          build, serve on localhost, rebuild on change
+//   volaro routes [project]       print discovered pages and the page-server route manifest
 //   volaro crib | volaro spec         print the language reference
 //   volaro example <name>         print a worked example
 //   volaro version | volaro help
@@ -12,7 +13,7 @@
 // Python is located and version-checked up front with an actionable message
 // (see ../lib/env.js). Nothing here depends on the Volaro repository layout.
 
-import { readFileSync, existsSync, statSync, lstatSync, readdirSync } from "node:fs";
+import { appendFileSync, readFileSync, existsSync, statSync, lstatSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve as resolvePath, extname, relative, sep, delimiter } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
@@ -72,12 +73,334 @@ function pyInvocation(pp, moduleName, moduleArgs) {
   return { cmd: py.cmd, argv: ["-B", "-m", moduleName, ...moduleArgs], env };
 }
 
+function elapsedMs(start) {
+  return Number(process.hrtime.bigint() - start) / 1e6;
+}
+
+function roundedMs(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function benchmarkRecords(path, runId) {
+  if (!existsSync(path)) return [];
+  let raw;
+  try {
+    const st = statSync(path);
+    if (st.isDirectory()) {
+      fail(`${CLI}: benchmark log ${path} is a directory, not a file`);
+    }
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    fail(`${CLI}: cannot read benchmark log ${path}: ${err.message}`);
+  }
+  return raw
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        fail(`${CLI}: invalid JSONL in benchmark log ${path} at line ${index + 1}: ` +
+             `${JSON.stringify(line.length > 80 ? line.slice(0, 80) + "…" : line)}`);
+      }
+    })
+    .filter((row) => row.schema === "volaro.compile-timing.v1" && row.run_id === runId);
+}
+
+function appendBenchmark(path, record) {
+  try {
+    appendFileSync(path, JSON.stringify(record) + "\n", { encoding: "utf8", flag: "a" });
+  } catch (err) {
+    fail(`${CLI}: cannot append benchmark log ${path}: ${err.message}`);
+  }
+}
+
+function ensureBenchmarkLog(path) {
+  try {
+    appendFileSync(path, "", { encoding: "utf8", flag: "a" });
+  } catch (err) {
+    fail(`${CLI}: cannot open benchmark log ${path}: ${err.message}`);
+  }
+}
+
+function compilerProvenance() {
+  try {
+    return JSON.parse(readFileSync(join(COMPILER, "SOURCE_INFO.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function parseBenchmarkArgs(args, command) {
+  let log = null;
+  let runId = null;
+  let logCount = 0;
+  let runCount = 0;
+  const compilerArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--benchmark-log" || arg === "--benchmark-run") {
+      if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
+        fail(`${CLI} ${command}: ${arg} requires a value`, 2);
+      }
+      if (arg === "--benchmark-log") {
+        log = args[++i];
+        logCount++;
+      } else {
+        runId = args[++i];
+        runCount++;
+      }
+    } else if (arg.startsWith("--benchmark-log=")) {
+      log = arg.slice("--benchmark-log=".length);
+      logCount++;
+    } else if (arg.startsWith("--benchmark-run=")) {
+      runId = arg.slice("--benchmark-run=".length);
+      runCount++;
+    } else {
+      compilerArgs.push(arg);
+    }
+  }
+  if ((log === null) !== (runId === null)) {
+    fail(`${CLI} ${command}: --benchmark-log and --benchmark-run must be supplied together`, 2);
+  }
+  if (logCount > 1 || runCount > 1) {
+    fail(`${CLI} ${command}: benchmark options may be supplied only once`, 2);
+  }
+  if (log !== null && log.trim() === "") {
+    fail(`${CLI} ${command}: --benchmark-log must not be empty`, 2);
+  }
+  if (runId !== null && runId.trim() === "") {
+    fail(`${CLI} ${command}: --benchmark-run must not be empty`, 2);
+  }
+  return {
+    args: compilerArgs,
+    benchmark: log === null ? null : { log: resolvePath(log), runId },
+  };
+}
+
+// Four possible outcomes for a FAILED attempt (never called for exitCode 0).
+// This is the entire classification: it never inspects captured stdout/
+// stderr TEXT, only (a) whether the OS delivered a kill signal and (b)
+// the compiler's own structural report of what kind of stop it made (see
+// `vlcheck/benchmark_signal.py`'s module docstring). "Any output happened"
+// is deliberately NOT a diagnostic signal on its own -- an internal
+// traceback is output too.
+function classifyAttempt(signal, benchmarkSignal, firstOutputMs) {
+  if (signal) return "operational_failure"; // killed by the OS, never a diagnostic
+  if (benchmarkSignal) {
+    if (benchmarkSignal.kind === "crash") return "operational_failure";
+    if (benchmarkSignal.kind === "diagnostic") {
+      // Each module's OWN reserved "diagnostics found in valid input" code
+      // is exactly 1 (see vlcheck/vlbuild __main__.py); any other code the
+      // compiler intentionally stopped with (a usage/configuration error,
+      // for instance) is a real, honest stop but not a SOURCE diagnostic.
+      return benchmarkSignal.exit_code === 1 ? "source_diagnostic" : "operational_failure";
+    }
+  }
+  // No structured signal reached us at all: the compiler crashed before
+  // reaching its own signal-emission wrapper (an import-time failure, an
+  // interpreter that never started, a segfault) or the side channel was
+  // lost. Distinguished only by whether anything was captured on stdout/
+  // stderr, not by reading it.
+  return firstOutputMs === null ? "silent_failure" : "unknown_failure";
+}
+
+function writeBenchmarkResult(benchmark, command, compilerArgv, code, signal, startedAt,
+                              startedMono, firstOutputMs, benchmarkSignal) {
+  const finishedEpochMs = Date.now();
+  const durationMs = elapsedMs(startedMono);
+  const prior = benchmarkRecords(benchmark.log, benchmark.runId);
+  if (prior.some((row) => row.record === "summary")) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} is already complete`, 2);
+  }
+
+  const attempts = prior.filter((row) => row.record === "attempt");
+  const exitCode = signal ? 1 : code ?? 0;
+  const provenance = compilerProvenance();
+  const classification = exitCode === 0 ? null : classifyAttempt(signal, benchmarkSignal, firstOutputMs);
+  const attempt = {
+    schema: "volaro.compile-timing.v1",
+    record: "attempt",
+    run_id: benchmark.runId,
+    attempt: attempts.length + 1,
+    command,
+    compiler_argv: compilerArgv,
+    compiler_version: pkg.version,
+    compiler_revision: provenance.revision || null,
+    compiler_content_sha256: provenance.content_sha256 || null,
+    started_at: startedAt,
+    finished_at: new Date(finishedEpochMs).toISOString(),
+    exit_code: exitCode,
+    signal: signal || null,
+    outcome: exitCode === 0 ? "success" : "failure",
+    classification,
+    duration_ms: roundedMs(durationMs),
+    // Raw fact, any classification: did output arrive, and when -- kept
+    // even for a crash/silent/unknown failure as the "available output
+    // metadata" a human investigating an invalid run needs.
+    first_output_ms: firstOutputMs === null ? null : roundedMs(firstOutputMs),
+    // Only ever populated for a genuine source diagnostic -- T-fail's
+    // whole point is "how long until the compiler told you about YOUR
+    // bug", which an operational/silent/unknown failure never did.
+    first_diagnostic_ms: classification === "source_diagnostic" && firstOutputMs !== null
+      ? roundedMs(firstOutputMs) : null,
+    crash_exception_type: benchmarkSignal && benchmarkSignal.kind === "crash"
+      ? benchmarkSignal.exception_type : null,
+    crash_exception_message: benchmarkSignal && benchmarkSignal.kind === "crash"
+      ? benchmarkSignal.exception_message : null,
+  };
+  appendBenchmark(benchmark.log, attempt);
+
+  if (exitCode !== 0) return;
+
+  const allAttempts = [...attempts, attempt];
+  const failures = allAttempts.filter((row) => row.outcome === "failure");
+  if (failures.length === 0) {
+    appendBenchmark(benchmark.log, {
+      schema: "volaro.compile-timing.v1",
+      record: "summary",
+      run_id: benchmark.runId,
+      command,
+      outcome: "clean",
+      timing_complete: true,
+      timing_incomplete_reason: null,
+      clock_anomaly: false,
+      attempt_count: 1,
+      failed_attempts: 0,
+      t_clean_ms: attempt.duration_ms,
+      t_fail_ms: null,
+      t_repair_ms: null,
+      t_recompile_ms: null,
+      t_recover_ms: null,
+      compiler_overhead_ms: null,
+    });
+    return;
+  }
+
+  // Wall-clock gaps between separate process invocations, computed from
+  // each process's own Date.now()-derived timestamps -- vulnerable to a
+  // backward system clock step (an NTP sync) between two attempts. A
+  // negative gap is never clamped to zero and reported as if it were a
+  // real, small repair time: that would silently corrupt the median/p90
+  // aggregation STAGE3-PROTOCOL.md §6.1 defines over this data. Instead
+  // the whole run is marked invalid for recovery-time comparison, with
+  // every raw timestamp still preserved untouched in the attempts above.
+  let repairMs = 0;
+  let clockAnomaly = false;
+  for (let i = 1; i < allAttempts.length; i++) {
+    const previous = allAttempts[i - 1];
+    if (previous.outcome === "failure") {
+      const gap = Date.parse(allAttempts[i].started_at) - Date.parse(previous.finished_at);
+      if (gap < 0) clockAnomaly = true;
+      repairMs += gap;
+    }
+  }
+  const first = allAttempts[0];
+  const recoverMs = finishedEpochMs - Date.parse(first.started_at);
+  if (recoverMs < 0) clockAnomaly = true;
+
+  const firstIsDiagnostic = first.classification === "source_diagnostic";
+  const failMs = firstIsDiagnostic ? first.first_diagnostic_ms : null;
+  const timingComplete = firstIsDiagnostic && !clockAnomaly;
+  const compilerOverheadMs = timingComplete
+    ? recoverMs - failMs - repairMs - attempt.duration_ms
+    : null;
+
+  let timingIncompleteReason = null;
+  if (!firstIsDiagnostic) {
+    timingIncompleteReason = `the original failing attempt was classified ` +
+      `${JSON.stringify(first.classification)}, not "source_diagnostic" -- ` +
+      `t_fail_ms and compiler_overhead_ms are not valid recovery-time samples for this run`;
+  } else if (clockAnomaly) {
+    timingIncompleteReason = "a wall-clock timestamp in this run predates an earlier one " +
+      "(a backward system clock step between two compiler invocations) -- " +
+      "t_repair_ms/t_recover_ms/compiler_overhead_ms are not valid recovery-time samples for this run";
+  }
+
+  appendBenchmark(benchmark.log, {
+    schema: "volaro.compile-timing.v1",
+    record: "summary",
+    run_id: benchmark.runId,
+    command,
+    outcome: "recovered",
+    timing_complete: timingComplete,
+    timing_incomplete_reason: timingIncompleteReason,
+    clock_anomaly: clockAnomaly,
+    attempt_count: allAttempts.length,
+    failed_attempts: failures.length,
+    t_clean_ms: null,
+    t_fail_ms: failMs,
+    t_repair_ms: clockAnomaly ? null : roundedMs(repairMs),
+    t_recompile_ms: attempt.duration_ms,
+    t_recover_ms: clockAnomaly ? null : roundedMs(recoverMs),
+    compiler_overhead_ms: timingComplete ? roundedMs(Math.max(0, compilerOverheadMs)) : null,
+  });
+}
+
 // Run a Python module, streaming its output, and exit with its status.
-function runPython(pp, moduleName, moduleArgs) {
+function runPython(pp, moduleName, moduleArgs, benchmark = null, command = moduleName) {
   const { cmd, argv, env } = pyInvocation(pp, moduleName, moduleArgs);
-  const child = spawn(cmd, argv, { stdio: "inherit", env });
+  if (!benchmark) {
+    const child = spawn(cmd, argv, { stdio: "inherit", env });
+    child.on("error", (e) => fail(`${CLI}: failed to start Python (${cmd}): ${e.message}`));
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 0));
+    return;
+  }
+
+  ensureBenchmarkLog(benchmark.log);
+  const existing = benchmarkRecords(benchmark.log, benchmark.runId);
+  if (existing.some((row) => row.record === "summary")) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} is already complete`, 2);
+  }
+  if (existing.some((row) => row.record === "attempt" && row.command !== command)) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} cannot mix check and build`, 2);
+  }
+  const compilerArgv = [moduleName, ...moduleArgs];
+  if (existing.some((row) => row.record === "attempt" &&
+      JSON.stringify(row.compiler_argv) !== JSON.stringify(compilerArgv))) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} must reuse the exact compiler command`, 2);
+  }
+
+  const startedEpochMs = Date.now();
+  const startedAt = new Date(startedEpochMs).toISOString();
+  const startedMono = process.hrtime.bigint();
+  let firstOutputMs = null;
+  // fd 3: a private side channel the compiler writes its own structural
+  // diagnostic/crash signal to (see vlcheck/benchmark_signal.py) -- never
+  // stdout/stderr, so ordinary output forwarded to the terminal below is
+  // untouched by this. VOLARO_BENCHMARK_SIGNAL_FD tells the compiler that
+  // channel exists; it is a documented no-op when unset, which is exactly
+  // every non-benchmark invocation.
+  const child = spawn(cmd, argv, {
+    stdio: ["inherit", "pipe", "pipe", "pipe"],
+    env: { ...env, PYTHONUNBUFFERED: "1", VOLARO_BENCHMARK_SIGNAL_FD: "3" },
+  });
+  const forward = (stream, target) => stream.on("data", (chunk) => {
+    if (firstOutputMs === null) firstOutputMs = elapsedMs(startedMono);
+    target.write(chunk);
+  });
+  forward(child.stdout, process.stdout);
+  forward(child.stderr, process.stderr);
+  const signalChunks = [];
+  child.stdio[3].on("data", (chunk) => signalChunks.push(chunk));
   child.on("error", (e) => fail(`${CLI}: failed to start Python (${cmd}): ${e.message}`));
-  child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 0));
+  child.on("close", (code, signal) => {
+    let benchmarkSignal = null;
+    const signalRaw = Buffer.concat(signalChunks).toString("utf8").trim();
+    if (signalRaw) {
+      // The compiler writes exactly one JSON line and closes the stream
+      // (benchmark_signal.py); take the first line defensively rather than
+      // assuming that held.
+      try {
+        benchmarkSignal = JSON.parse(signalRaw.split(/\r?\n/)[0]);
+      } catch {
+        benchmarkSignal = null; // malformed signal -> falls through to unknown_failure
+      }
+    }
+    writeBenchmarkResult(benchmark, command, compilerArgv, code, signal, startedAt,
+                         startedMono, firstOutputMs, benchmarkSignal);
+    process.exit(signal ? 1 : code ?? 0);
+  });
 }
 
 function pyCapture(pp, moduleName, moduleArgs) {
@@ -88,9 +411,10 @@ function pyCapture(pp, moduleName, moduleArgs) {
 // ---- subcommands -----------------------------------------------------------
 
 function cmdCheck(args) {
-  if (args.length === 0) fail("usage: volaro check <file-or-dir>... [--release] [--config PATH]");
+  const parsed = parseBenchmarkArgs(args, "check");
+  if (parsed.args.length === 0) fail("usage: volaro check <file-or-dir>... [--release] [--config PATH]");
   // Always resolve: a bare structural pass is weaker than the real check.
-  runPython(VALIDATOR_PP, "vlcheck", ["--resolve", ...args]);
+  runPython(VALIDATOR_PP, "vlcheck", ["--resolve", ...parsed.args], parsed.benchmark, "check");
 }
 
 function parseBuildArgs(args) {
@@ -123,14 +447,15 @@ function resolveEntry(explicit) {
 }
 
 function cmdBuild(args) {
-  const b = parseBuildArgs(args);
+  const parsed = parseBenchmarkArgs(args, "build");
+  const b = parseBuildArgs(parsed.args);
   const source = resolveEntry(b.source);
   const outDir = b.o ? resolvePath(b.o) : resolvePath("build");
   const pyArgs = [source, "-o", outDir];
   if (b.data) pyArgs.push("--data", resolvePath(b.data));
   if (b.config) pyArgs.push("--config", resolvePath(b.config));
   if (b.release) pyArgs.push("--release");
-  runPython(VLBUILD_PP, "vlbuild", pyArgs);
+  runPython(VLBUILD_PP, "vlbuild", pyArgs, parsed.benchmark, "build");
 }
 
 // Synchronous single build for `volaro dev`; returns { ok, server } or exits on env error.
@@ -263,7 +588,9 @@ function cmdDev(args) {
   if (!Number.isInteger(port) || port < 1 || port > 65535) fail("volaro dev: --port must be 1..65535");
   const entry = resolveEntry(source);
   const out = outDir ? resolvePath(outDir) : resolvePath("build");
-  const watchDir = dirname(entry);
+  // A project build's entry is the project directory itself (`volaro dev .`);
+  // watching its dirname would watch the PARENT directory instead.
+  const watchDir = statSync(entry).isDirectory() ? entry : dirname(entry);
 
   process.stdout.write(`volaro dev: building ${relative(process.cwd(), entry) || entry}\n`);
   const first = buildOnce(entry, out);
@@ -388,6 +715,20 @@ function cmdExample(name) {
   else fail("usage: volaro example sensors|station");
 }
 
+function cmdRoutes(args) {
+  let json = false;
+  let project = null;
+  for (const a of args) {
+    if (a === "--json") json = true;
+    else if (a.startsWith("-")) fail(`usage: volaro routes [project] [--json]`, 2);
+    else if (!project) project = a;
+    else fail(`usage: volaro routes [project] [--json]`, 2);
+  }
+  const pyArgs = [resolvePath(project || ".")];
+  if (json) pyArgs.push("--json");
+  runPython(VALIDATOR_PP, "vlcheck.routes_cli", pyArgs);
+}
+
 const HELP = `Volaro ${pkg.version} — an application language for AI authoring and human review.
 
 USAGE
@@ -397,15 +738,27 @@ USAGE
 COMMANDS
   check <path>...        Validate .vl source. Runs the full resolver, not just
                          a structural pass. Exit non-zero on any error.
+      --benchmark-log <file>  append raw timing records as JSONL
+      --benchmark-run <id>    group attempts into one clean/recovery trial
   build <file.vl>        Transpile to a runnable bundle (default: ./build).
       -o <dir>             output directory
       --data <file>        data.json to bundle
       --release            fail on unresolved placeholders (e.g. img alt_todo:)
+      --benchmark-log <file>  append raw timing records as JSONL
+      --benchmark-run <id>    group attempts into one clean/recovery trial
   dev [file.vl]          Build, serve on http://127.0.0.1:5173, and rebuild
                          when a .vl file changes. Defaults to ./app.vl. A
                          full-stack build runs server.js instead (Node 22.5+)
                          and restarts it after each successful rebuild.
       --port <n>           dev server port (passed to server.js as $PORT)
+  routes [project]       Print discovered browser pages (spec §8.15: URL,
+                         source, layout chain, boundaries) and the
+                         page-server route manifest (spec §10.2: final URL,
+                         method, source file, parameter types, generated
+                         client member, authorization). Project defaults to
+                         ".". Exits non-zero on any collision or project-
+                         validity error (page/route or layout-composition).
+      --json               emit the language-neutral manifest as JSON
   crib                   The authoring reference (write from this).
   supported             What version ${pkg.version} actually accepts.
   spec                   The full language design (a SUPERSET of this build).
@@ -416,12 +769,13 @@ COMMANDS
 The compiler is Python and ships inside this package. Set VOLARO_PYTHON to
 choose the interpreter if \`python3\` is not the one you want.
 
-SHIPPED SUBSET: single page (no router); text \`input\` / \`button\` / \`link\`
-only (no checkbox/select/textarea/disabled — a toggle is a \`button\` + \`state\`,
-not a semantic checkbox); \`if\` as an expression is binary; \`match\` is a
-statement; a module-level \`fn\` cannot be called from a view. \`volaro crib\` +
-\`volaro supported\` are authoritative for this build; \`volaro spec\` is the wider
-design, not what it accepts.
+SHIPPED SUBSET: single page (no router); \`input\` (full type matrix incl.
+checkbox/radio), \`textarea\`, \`select\`/\`option\`/\`optgroup\`,
+\`fieldset\`/\`legend\`, \`datalist\`, \`button\`, \`link\` (no standalone
+\`label\`, no semantic switch/aria-pressed toggle); \`if\` as an expression is
+binary; \`match\` is a statement; a module-level \`fn\` cannot be called from a
+view. \`volaro crib\` + \`volaro supported\` are authoritative for this build;
+\`volaro spec\` is the wider design, not what it accepts.
 
 Run commands via your project's \`npm run …\` scripts or \`npx --no-install
 volaro …\` inside the project. A bare \`npx volaro …\` from elsewhere may fetch
@@ -444,6 +798,9 @@ switch (cmd) {
   case "dev":
     cmdDev(rest);
     break;
+  case "routes":
+    cmdRoutes(rest);
+    break;
   case "crib":
     cmdReference("crib");
     break;

package/compiler/SOURCE_INFO.json

@@ -1,6 +1,6 @@
 {
-  "revision": "a450e6fe6549b8c7df43ba343793ab2e52758a78",
+  "revision": "0d5741da1385dd81e277b16715a93592744d8c87",
   "source": "git",
   "dirty": false,
-  "content_sha256": "095f3d5b55826d6aa0c560ce5570c91752d8f03cbd0e869ce61df1fcf53e2593"
+  "content_sha256": "611292080bf797022be28aea42376ca55bbeba3e680c2ec638ae4a1417981ff0"
 }

package/compiler/SOURCE_REV

@@ -1 +1 @@
-a450e6fe6549b8c7df43ba343793ab2e52758a78
+0d5741da1385dd81e277b16715a93592744d8c87