volaro 0.1.0-alpha.1 → 0.1.0-alpha.4

package/README.md

@@ -1,7 +1,8 @@
 # Volaro
 
-**Limited alpha (`0.1.0-alpha.1`). Not yet published to npm.** Install from a
-local `npm pack` tarball to try it.
+**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.
 
 Volaro is an experimental application language intended for AI authoring and
 human review. This package ships the language reference **and a working
@@ -58,16 +59,66 @@ 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
 
 ```bash
-npm create volaro my-app      # the separate create-volaro package
+npm create volaro@alpha my-app      # the separate create-volaro package
 ```
 
+(`@alpha` matters — `npm create volaro` with no tag resolves `latest`, which
+is still an earlier `0.0.x` placeholder, not this build.)
+
 It writes one single-page starter, a `volaro.json`, and `package.json` scripts
 (`dev` / `build` / `check`) that call `volaro`.
 
@@ -78,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
 
@@ -89,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
@@ -110,3 +176,25 @@ The legacy `volara` npm package is unrelated to this release.
 ## License
 
 MIT
+
+
+## Local assets
+
+Put public files in `assets/` beside your entry `.vl` file and use
+`img src:"assets/logo.svg" alt:"Logo"`. Build and dev copy them to the browser
+bundle. Dev watches changes; refresh the browser after a rebuild. Missing
+literal asset references fail the build. Output `assets/` is compiler-owned.
+
+## Package provenance
+
+`compiler/SOURCE_REV` records the source commit. `compiler/SOURCE_INFO.json`
+adds its origin, Git dirty status where available, and a SHA-256 digest of
+compiler and CLI/documentation content. A package version alone does not
+identify a local candidate; preserve the tarball hash as well.
+
+Packaging a Git export uses `.volaro-source-rev`, expanded by `git archive`.
+For other exported source, set `VOLARO_SOURCE_REV` to the full source commit
+hash before `npm pack`. Missing/invalid revisions fail packaging; an explicit
+revision cannot override a different checkout HEAD. Export metadata identifies
+the base revision, not an assurance that someone has not modified the export;
+the content hash distinguishes modified candidates. Nothing is published by packing.