@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/docs/dgx-spark.md

@@ -0,0 +1,64 @@
+# August on DGX Spark
+
+August's LLVM compiler built and ran on a physical DGX Spark on October 2, 2026. It passed the language regression suite, safety gyms, and installed-CLI checks for all four public native libraries. These are CPU results. They do not qualify GPU execution or the rest of PyTorch's API.
+
+## Machine and measurement
+
+The host ran Ubuntu 24.04.4 LTS, Linux 6.17.0-1021-nvidia, on a 20-core ARM64 CPU with Cortex-X925 and Cortex-A725 cores. Builds used August's Debian 12 maintainer container: glibc 2.36, Node 24.21.0, LLVM 23.1.2, and Debian Clang 14.0.6 for the independent C references. The container ran directly on the Spark's ARM64 CPU.
+
+Timed runs were restricted to four performance cores, CPUs 5–8. Frequency and other host activity were not fixed. Each sample started a fresh executable; timings include process startup and exclude compilation. Implementation order rotated in a separate measurement process, and every output was checked. Both August and C used O2 without LTO or fast-math. Compare implementations within a row; do not treat these numbers as a comparison of Spark and the [Mac results](qualification-results.md).
+
+The raw reports say `unknown` for the CPU model because Node did not expose its name in the container. The hardware description above comes from the host's `lscpu` inventory. The reports are preserved as recorded.
+
+## Core workloads
+
+These medians use 60 samples after three warmups. [The full report](dgx-performance.json) includes all samples, peak memory, build times, Node and Python comparisons, and the C migration backend. The [performance guide](performance.md) explains the programs and their comparison limits.
+
+| Program | Work per run | August LLVM | C | August / C |
+| --- | ---: | ---: | ---: | ---: |
+| Startup | Print one integer | 1.33 ms | 0.92 ms | 1.44 |
+| Integer loop | 2,000,000 steps | 7.77 ms | 7.51 ms | 1.04 |
+| Map and Set | 20,000 entries | 4.24 ms | 3.70 ms | 1.15 |
+| Map and Set | 200,000 entries | 63.48 ms | 22.47 ms | 2.83 |
+| JSON | 5,000 records | 7.19 ms | 1.60 ms | 4.49 |
+
+The larger collection case and JSON still have substantial overhead. The JSON C reference parses and writes data without constructing August records. A passing migration gate means LLVM stayed within the frozen limits against the same August program compiled through C; it does not mean every program matches a specialized C implementation.
+
+## Eight application kernels
+
+These medians use 30 samples after three warmups. Each linked project shows the complete August code beside its compiled explanation, with an indentation/braces switch. [Raw samples and expected results](dgx-kernels.json) retain the C migration comparison too.
+
+| Program and code/spec | Work per run | August LLVM | C | August / C |
+| --- | ---: | ---: | ---: | ---: |
+| [Floating-point loop](examples/float-benchmark/main.md) | 1,000,000 | 2.15 ms | 1.57 ms | 1.37 |
+| [Labeled calls](examples/calls-benchmark/main.md) | 200,000 | 2.50 ms | 1.58 ms | 1.59 |
+| [List traversal](examples/list-benchmark/main.md) | 100,000 | 3.62 ms | 1.96 ms | 1.84 |
+| [String processing](examples/strings-benchmark/main.md) | 20,000 | 8.29 ms | 2.07 ms | 4.00 |
+| [Map deletion and refill](examples/map-churn-benchmark/main.md) | 4,000 | 5.31 ms | 4.47 ms | 1.19 |
+| [Checked failures](examples/errors-benchmark/main.md) | 20,000 | 1.04 ms | 0.72 ms | 1.43 |
+| [Record allocation](examples/records-benchmark/main.md) | 50,000 | 22.60 ms | 3.09 ms | 7.32 |
+| [Task scheduling](examples/tasks-benchmark/main.md) | 2,000 | 8.23 ms | 1.30 ms | 6.32 |
+
+The [C references](https://github.com/GreenPandaStudios/augscript/blob/e3c072be276e9801d348690435c08c4b146fd352/benchmarks/kernels.c) use concrete representations and explicit cleanup. The ordered map uses linear search. The task reference calls functions sequentially; it does not implement August's scheduler or cancellation rules. Managed strings, records and tasks remain useful targets for further optimization. The benchmark checks their behavior rather than removing that behavior to improve a number.
+
+## HTTP throughput
+
+Each median covers five fresh server runs with 5,000 validated requests per run, after warmup. The load is HTTP/1.1 loopback with keep-alive, fixed concurrency and no TLS, authentication or logging. It measures this endpoint and client together, not a server's maximum capacity. There is no standalone C HTTP implementation in this comparison.
+
+| Concurrent clients | August LLVM | August C backend | Node |
+| --- | ---: | ---: | ---: |
+| 1 | 18,441 requests/s | 16,157 requests/s | 17,271 requests/s |
+| 16 | 37,864 requests/s | 38,866 requests/s | 34,749 requests/s |
+| 64 | 35,395 requests/s | 36,414 requests/s | 31,815 requests/s |
+
+## Safety and real imports
+
+All **266 LLVM parity tests** passed with no skips, including source breakpoints and debugger variable inspection. The full [safety gym report](dgx-gyms.json) passed 3,612 generated and edge-case checks in development and optimized builds, rejected eight forbidden contracts, and detected all 14 valid behavioral mutations. All six additional circuits passed with no skipped tests: source mutations, ownership/concurrency, native boundaries, package integrity, HTTP boundaries and sanitizers.
+
+The [installed-CLI report](dgx-consumers.json) records public URL imports and named aliases for CPU LibTorch `v0.1.4`, SQLite `v0.1.3`, zlib `v0.1.3`, and Rust BLAKE3 `v0.1.3`. The real libraries produced the expected tensor sum, database query, compression round trip and hash. Frozen/offline restores, relocated deployments, same-file tests, resource cleanup counters, tasks, JSON, clocks, crypto and HTTP forms passed too. The test processes had no native developer tools on their search path; the unpublished compiler archive was supplied locally. The separate clean-container CI checks remove compilers, Git and development headers from the consumer filesystem.
+
+These finite tests do not prove arbitrary foreign code safe. Core sanitizers do not instrument the interiors of prebuilt libraries, and the coroutine gate does not establish whole-process leak freedom. Read the [gym limits](safety-gyms.md) before interpreting a pass.
+
+## Revision
+
+This run used commit [`e3c072b`](https://github.com/GreenPandaStudios/augscript/commit/e3c072be276e9801d348690435c08c4b146fd352). All three benchmark/gym reports carry source SHA-256 `d6afc98df62d8a40990cf4032cf01595e8c353bf7419d44ddfefa7c479681a79`, which includes the platform's prepared compiler-pack metadata. The results apply to that recorded snapshot. [Contributor instructions](contributing-benchmarks.md) explain how to produce new evidence after a change.

package/docs/diagnostics.md

@@ -4,7 +4,7 @@ Start with the diagnostic's file, line, and message. The code identifies the rul
 
 Terminal diagnostics include the source line, a pointer to the location, and a `help:` explanation. `aug check --json` preserves structured diagnostics for tooling. Fix the first dependency or configuration error before investigating follow-on name errors.
 
-If `aug run` cannot prepare or start a program, its message identifies the failed stage. A missing C compiler includes the host installation command and the `CC` override. A failed download identifies the library and URL; retry after checking the connection. A failed native build links its log. An offline cache miss explains how to prepare it online. Changed installed source packages require an explicit `aug install` so a run does not hide unexpected edits. A program stopped by a signal reports that signal after its own runtime output.
+If `aug run` cannot prepare or start a program, its message identifies the failed stage. A missing or incompatible artifact names the required platform and version. A failed download identifies the library and URL; retry after checking the connection. An offline cache miss explains how to prepare it online. C reference builds report missing host tools separately. Changed installed source packages require an explicit `aug install` so a run does not hide unexpected edits. A program stopped by a signal reports that signal after its own runtime output.
 
 When a fix changes a dependency, effect, error, or mutable input, review the caller's contract too. A suggested edit can satisfy a language rule without deciding the right recovery or design for your application. [The book](learn/index.md) includes deliberate mistakes you can check and repair yourself.
 

package/docs/docker.md

@@ -4,36 +4,30 @@ Compile an August application in a Linux build container, then deploy its execut
 
 ## Prepare the toolchain images
 
-Build two local images from the published npm CLI. The **build** image contains Node.js 24, the August compiler, Clang and its sanitizer runtime, and the pinned native task, JSON, web, and crypto dependencies. The **run** image is a small Debian userland with matching native shared libraries and CA certificates. It runs a compiled August executable as an unprivileged user. These are local image recipes; August does not currently publish registry tags for them.
+Build two local images. The build image contains Node.js 24 and the August CLI; `aug build` downloads its verified LLVM/runtime pack and package artifacts. The run image supplies Debian's runtime and CA certificates. It runs the executable and its neighboring libraries as an unprivileged user. These are local recipes; August does not publish registry tags for them. They target the pending 0.21.0 release.
 
-Save this as `Dockerfile.build` in an empty working folder. It installs the published toolchain, then prepares its native dependencies. Pin `AUG_VERSION` to the version used by your application:
+Save this as `Dockerfile.build` in an empty working folder. Pin `AUG_VERSION` to the version used by your application:
 
 ```dockerfile
 FROM node:24-bookworm
-ARG AUG_VERSION=0.20.1
-ENV AUG_NATIVE_HOME=/opt/augscript/.aug-native
+ARG AUG_VERSION=0.21.0
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends \
-       git clang libclang-rt-14-dev make cmake m4 autoconf \
-       automake libtool python3 zlib1g-dev ca-certificates \
+    && apt-get install -y --no-install-recommends ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 RUN npm install --global --ignore-scripts --no-audit --no-fund \
-       @greenpandastudios/aug-cli@${AUG_VERSION} \
-    && aug-native
+       @greenpandastudios/aug-cli@${AUG_VERSION}
 WORKDIR /workspace
 ENTRYPOINT ["aug"]
 CMD ["--help"]
 ```
 
-Save this as `Dockerfile.run` beside it. Keeping the same native library path preserves the executable's runtime search path:
+Save this as `Dockerfile.run` beside it. Each application supplies its own `lib` and `share` directories beside the executable:
 
 ```dockerfile
-FROM augscript/build:local AS native
 FROM debian:bookworm-slim
 RUN apt-get update \
     && apt-get install -y --no-install-recommends ca-certificates zlib1g \
     && rm -rf /var/lib/apt/lists/*
-COPY --from=native /opt/augscript/.aug-native/prefix/lib /opt/augscript/.aug-native/prefix/lib
 RUN groupadd --system august \
     && useradd --system --gid august --home-dir /app august
 WORKDIR /app
@@ -48,7 +42,7 @@ docker build -f Dockerfile.build -t augscript/build:local .
 docker build -f Dockerfile.run -t augscript/run:local .
 ```
 
-The first build downloads and compiles native dependencies; later builds can reuse Docker's cached layers. Keep these local images on the same Docker engine that builds your application.
+The first application build downloads the compiler and required artifacts; later builds reuse their verified cache. Keep these local images on the same Docker engine that builds your application.
 
 ## Compile an existing project
 
@@ -59,11 +53,15 @@ Keep the project in a directory shared with your Docker engine. If Docker report
 ```sh
 docker run --rm \
   --user "$(id -u):$(id -g)" \
+  --env AUG_NATIVE_ARTIFACT_CACHE=/workspace/.aug-build/artifact-cache \
+  --env AUG_PACKAGE_CACHE=/workspace/.aug-build/source-cache \
   --mount type=bind,source="$PWD/my-app",target=/workspace \
   augscript/build:local install .
 
 docker run --rm \
   --user "$(id -u):$(id -g)" \
+  --env AUG_NATIVE_ARTIFACT_CACHE=/workspace/.aug-build/artifact-cache \
+  --env AUG_PACKAGE_CACHE=/workspace/.aug-build/source-cache \
   --mount type=bind,source="$PWD/my-app",target=/workspace \
   augscript/build:local build . --out /workspace/.aug-build/program
 ```
@@ -76,7 +74,7 @@ docker run --rm \
   augscript/run:local
 ```
 
-The two images use the same Debian distribution and native library paths. A Linux executable built here runs inside the runtime container, including when your host is macOS or Windows.
+The cache path is inside the writable project mount so it belongs to your host user. The images use the same Debian distribution. The executable loads libraries from its neighboring `lib` directory; keep `share` for dependency notices and source provenance. A Linux executable built here runs inside the runtime container, including when your host is macOS or Windows.
 
 ## Deploy an HTTP application
 
@@ -129,10 +127,11 @@ Save this `Dockerfile` in `my-api`. Docker's [multi-stage build](https://docs.do
 ```dockerfile
 FROM augscript/build:local AS build
 COPY . /workspace
-RUN aug test /workspace \
-    && aug build /workspace --out /tmp/program
+RUN aug install /workspace \
+    && aug test /workspace \
+    && aug build /workspace --out /tmp/deploy/program
 FROM augscript/run:local
-COPY --from=build --chown=august:august /tmp/program /app/program
+COPY --from=build --chown=august:august /tmp/deploy/ /app/
 ```
 
 Save `.dockerignore` in the same folder:

package/docs/example-projects.json

@@ -1,4 +1,28 @@
 [
+  {
+    "path": "examples/native-pytorch",
+    "title": "CPU tensors with PyTorch",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Import real LibTorch from its public August package, add CPU tensors, and verify the elements and sum. Owned tensors are released when their scope ends."
+  },
+  {
+    "path": "examples/native-sqlite",
+    "title": "A database with SQLite",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Create an in-memory database, insert a labeled bound value, and query it through the real SQLite implementation. Mutation requires a borrow; scope exit closes the database."
+  },
+  {
+    "path": "examples/native-zlib",
+    "title": "Compression with zlib",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Compress a buffer with zlib and verify the restored bytes. A fixed output limit bounds decompression."
+  },
+  {
+    "path": "examples/native-blake3",
+    "title": "Hashing with Rust BLAKE3",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Import a Rust implementation through an ordinary August package and verify a published BLAKE3 hash vector."
+  },
   {
     "path": "examples/hello",
     "title": "Hello world with dependencies",
@@ -181,6 +205,14 @@
     "group": "Measured programs",
     "description": "The small program used to measure process startup."
   },
+  {"path":"benchmarks/float","title":"Floating-point benchmark","group":"Measured programs","description":"Accumulate exact binary fractions and check the final value."},
+  {"path":"benchmarks/calls","title":"Function-call benchmark","group":"Measured programs","description":"Call a labeled function repeatedly with a dependent integer result."},
+  {"path":"benchmarks/list","title":"List traversal benchmark","group":"Measured programs","description":"Grow a list and sum its snapshot values."},
+  {"path":"benchmarks/strings","title":"String processing benchmark","group":"Measured programs","description":"Split text into parts and sum their byte lengths."},
+  {"path":"benchmarks/map-churn","title":"Map deletion benchmark","group":"Measured programs","description":"Delete, replace and reinsert entries, then check values and insertion order."},
+  {"path":"benchmarks/errors","title":"Checked-error benchmark","group":"Measured programs","description":"Interleave successful calls and caught checked failures."},
+  {"path":"benchmarks/records","title":"Record allocation benchmark","group":"Measured programs","description":"Retain immutable records and sum their fields."},
+  {"path":"benchmarks/tasks","title":"Task scheduling benchmark","group":"Measured programs","description":"Start and join two tasks in each bounded scope."},
   {
     "path": "benchmarks/cpu",
     "title": "CPU benchmark",

package/docs/examples/approved-design/dependencies/august/{0.20.1 → 0.21.0}/io/contracts.md

@@ -1,7 +1,7 @@
 ---
-title: "august/0.20.1/io/contracts.aug · Modules and composition"
+title: "august/0.21.0/io/contracts.aug · Modules and composition"
 generated: true
-source: "examples/approved-design/.aug-spec/august/0.20.1/io/contracts.aug"
+source: "examples/approved-design/.aug-spec/august/0.21.0/io/contracts.aug"
 editLink: false
 prev: false
 next: false
@@ -10,7 +10,7 @@ search: false
 pageClass: aug-example-page
 ---
 
-# `august/0.20.1/io/contracts.aug`
+# `august/0.21.0/io/contracts.aug`
 
 [Modules and composition](../../../../index.md) · Dependency source and specification
 

package/docs/examples/approved-design/domain/app.md

@@ -82,19 +82,19 @@ The application's explicit startup operation.
 
 #### `Application.start` · [source](app.md#code) {#symbol-Application.start}
 
-Writes the fruit names through the selected console. It can call [`Console.write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
+Writes the fruit names through the selected console. It can call [`Console.write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
 ### `ApplicationImpl` · class · [source](app.md#code) {#symbol-ApplicationImpl}
 
-Construction stores dependencies; start performs the visible external work. It implements [`Application`](app.md#symbol-Application). The `console` dependency is injected as [`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console) and stored read-only.
+Construction stores dependencies; start performs the visible external work. It implements [`Application`](app.md#symbol-Application). The `console` dependency is injected as [`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console) and stored read-only.
 
 #### `ApplicationImpl.start` · [source](app.md#code) {#symbol-ApplicationImpl.start}
 
-Writes the fruit names through the selected console. It sets `fruit` to a list containing a [`Fruit`](models.md#symbol-Fruit) with `code` `1` and `name` `"apple"`, a [`Fruit`](models.md#symbol-Fruit) with `name` `"pear"` and `code` `2`. For each `item` in a snapshot of `fruit`, it passes `item.name` to [`console.write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
+Writes the fruit names through the selected console. It sets `fruit` to a list containing a [`Fruit`](models.md#symbol-Fruit) with `code` `1` and `name` `"apple"`, a [`Fruit`](models.md#symbol-Fruit) with `name` `"pear"` and `code` `2`. For each `item` in a snapshot of `fruit`, it passes `item.name` to [`console.write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
 ### Dependencies
 
-It uses [`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write)) from `august.io`. It uses [`Fruit`](models.md#symbol-Fruit) (`name`) from `models`.
+It uses [`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write)) from `august.io`. It uses [`Fruit`](models.md#symbol-Fruit) (`name`) from `models`.
 
 ::::
 

package/docs/examples/approved-design/main.md

@@ -113,7 +113,7 @@ catch RangeError error {
 
 ### Providers
 
-`Console` is provided by [`SystemConsole`](dependencies/august/0.20.1/io/contracts.md#symbol-SystemConsole). The same instance is shared.
+`Console` is provided by [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole). The same instance is shared.
 
 `Application` is provided by [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl). The same instance is shared. It requires bindings for `Console`. Include providers from [`Counters`](counters.md#symbol-Counters).
 
@@ -129,7 +129,7 @@ It calls [`double`](domain/numbers.md#symbol-double) with `amount` `-1`. If this
 
 ### Dependencies
 
-It uses [`SystemConsole`](dependencies/august/0.20.1/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Counter`](counters.md#symbol-Counter) ([`increment`](counters.md#symbol-Counter.increment) and [`value`](counters.md#symbol-Counter.value)) and [`Counters`](counters.md#symbol-Counters) from `counters`. It uses [`Application`](domain/app.md#symbol-Application) ([`start`](domain/app.md#symbol-Application.start)), [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl), [`Fruit`](domain/models.md#symbol-Fruit), [`RangeError`](domain/numbers.md#symbol-RangeError), and [`double`](domain/numbers.md#symbol-double) from `domain`.
+It uses [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Counter`](counters.md#symbol-Counter) ([`increment`](counters.md#symbol-Counter.increment) and [`value`](counters.md#symbol-Counter.value)) and [`Counters`](counters.md#symbol-Counters) from `counters`. It uses [`Application`](domain/app.md#symbol-Application) ([`start`](domain/app.md#symbol-Application.start)), [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl), [`Fruit`](domain/models.md#symbol-Fruit), [`RangeError`](domain/numbers.md#symbol-RangeError), and [`double`](domain/numbers.md#symbol-double) from `domain`.
 
 Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 

package/docs/examples/calls-benchmark/index.md

@@ -0,0 +1,36 @@
+---
+title: "Function-call benchmark"
+generated: true
+source: "benchmarks/calls"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Function-call benchmark
+
+Call a labeled function repeatedly with a dependent integer result.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+
+## Try this project
+
+[Download this project](/downloads/calls-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd calls-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

package/docs/examples/calls-benchmark/main.md

@@ -0,0 +1,78 @@
+---
+title: "main.aug · Function-call benchmark"
+generated: true
+source: "benchmarks/calls/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Function-call benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import step from operations
+int iterations = 200000
+int state = 123
+int index = 0
+while index < iterations:
+    state = step(value=state)
+    index = index + 1
+print(value=state)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import step from operations
+int iterations = 200000
+int state = 123
+int index = 0
+while index < iterations {
+    state = step(value=state)
+    index = index + 1
+}
+print(value=state)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `200000`. It sets `state` to `123`. It sets `index` to `0`. While `index` is less than `iterations`, it sets `state` to [`step`](operations.md#symbol-step) with `value` from `state`; then it increases `index` by `1`.
+
+After the loop, it prints `state`.
+
+### Dependencies
+
+It uses [`step`](operations.md#symbol-step) from `operations`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/calls-benchmark/operations.md

@@ -0,0 +1,60 @@
+---
+title: "operations.aug · Function-call benchmark"
+generated: true
+source: "benchmarks/calls/operations.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `operations.aug`
+
+[Function-call benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+step(int value) returns int:
+    int product = value * 48271 + 1
+    return product - product / 2147483647 * 2147483647
+```
+
+```aug [Braces]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+step(int value) returns int {
+    int product = value * 48271 + 1
+    return product - product / 2147483647 * 2147483647
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `step` · [source](operations.md#code) {#symbol-step}
+
+It takes `value` as an integer. It sets `product` to (`value` times `48271`) plus `1`. It returns `product` minus ((`product` divided by `2147483647`) times `2147483647`).
+
+::::
+
+:::::

package/docs/examples/developer-workflow/calculator.md

@@ -155,7 +155,7 @@ Adds two integers.
 
 #### `Arithmetic.add` · [source](calculator.md#code) {#symbol-Arithmetic.add}
 
-It takes `left` and `right` as integers. It gets `console` ([`Console`](dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It returns `int`. It can call [`Console.write`](dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
+It takes `left` and `right` as integers. It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It returns `int`. It can call [`Console.write`](dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
 ### `Calculator` · class · [source](calculator.md#code) {#symbol-Calculator}
 
@@ -163,7 +163,7 @@ Uses the selected logger to describe each addition. It implements [`Arithmetic`]
 
 #### `Calculator.add` · [source](calculator.md#code) {#symbol-Calculator.add}
 
-Adds left and right, logging the operation. It takes `left` as an integer (First integer) and `right` as an integer (Second integer). It gets `console` ([`Console`](dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It returns `int` — Sum of the two integers.
+Adds left and right, logging the operation. It takes `left` as an integer (First integer) and `right` as an integer (Second integer). It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It returns `int` — Sum of the two integers.
 
 It passes `"adding integers"` to [`_logger.log`](logging/logger.md#symbol-Logger.log), using injected `console`. It returns `left` plus `right`.
 
@@ -179,7 +179,7 @@ Test adapter: keeps calculator tests independent of console output. It implement
 
 #### `_SilentLogger.log` · [source](calculator.md#code) {#symbol-_SilentLogger.log}
 
-It takes `message` as a string (Text to write). It gets `console` ([`Console`](dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It continues without an operation.
+It takes `message` as a string (Text to write). It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It continues without an operation.
 
 ### `test Calculator calculator` · [source](calculator.md#code) {#symbol-test-20-Calculator-20-calculator}
 
@@ -187,7 +187,7 @@ Tests [`Calculator`](calculator.md#symbol-Calculator). Each case gets fresh setu
 
 #### `addition`
 
-Setup for each case: `Console` is provided by [`SystemConsole`](dependencies/august/0.20.1/io/contracts.md#symbol-SystemConsole). Stateless instances are reused; stateful instances are created for each resolve. `Logger` is provided by [`_SilentLogger`](calculator.md#symbol-_SilentLogger). Stateless instances are reused; stateful instances are created for each resolve.
+Setup for each case: `Console` is provided by [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole). Stateless instances are reused; stateful instances are created for each resolve. `Logger` is provided by [`_SilentLogger`](calculator.md#symbol-_SilentLogger). Stateless instances are reused; stateful instances are created for each resolve.
 
 It sets `calculator` to a [`Calculator`](calculator.md#symbol-Calculator) using injected `Logger` for `_logger`. It sets `values` of type `List<int>` to a list containing `1`, `2`.
 
@@ -201,7 +201,7 @@ The test requires the number of elements in `values` equals `2`. The test requir
 
 ### Dependencies
 
-It uses [`Console`](dependencies/august/0.20.1/io/contracts.md#symbol-Console) ([`write`](dependencies/august/0.20.1/io/contracts.md#symbol-Console.write)) and [`SystemConsole`](dependencies/august/0.20.1/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Logger`](logging/logger.md#symbol-Logger) ([`log`](logging/logger.md#symbol-Logger.log)) from `logging`.
+It uses [`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console) ([`write`](dependencies/august/0.21.0/io/contracts.md#symbol-Console.write)) and [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Logger`](logging/logger.md#symbol-Logger) ([`log`](logging/logger.md#symbol-Logger.log)) from `logging`.
 
 Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 

package/docs/examples/developer-workflow/dependencies/august/{0.20.1 → 0.21.0}/io/contracts.md

@@ -1,7 +1,7 @@
 ---
-title: "august/0.20.1/io/contracts.aug · A small tested application"
+title: "august/0.21.0/io/contracts.aug · A small tested application"
 generated: true
-source: "examples/developer-workflow/.aug-spec/august/0.20.1/io/contracts.aug"
+source: "examples/developer-workflow/.aug-spec/august/0.21.0/io/contracts.aug"
 editLink: false
 prev: false
 next: false
@@ -10,7 +10,7 @@ search: false
 pageClass: aug-example-page
 ---
 
-# `august/0.20.1/io/contracts.aug`
+# `august/0.21.0/io/contracts.aug`
 
 [A small tested application](../../../../index.md) · Dependency source and specification
 

package/docs/examples/developer-workflow/logging/console.md

@@ -67,11 +67,11 @@ Writes application messages to standard output. It implements [`Logger`](logger.
 
 #### `ConsoleLogger.log` · [source](console.md#code) {#symbol-ConsoleLogger.log}
 
-It takes `message` as a string (Text to write). It gets `console` ([`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It passes `message` to [`console.write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
+It takes `message` as a string (Text to write). It gets `console` ([`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It passes `message` to [`console.write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
 ### Dependencies
 
-It uses [`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write)) from `august.io`. It uses [`Logger`](logger.md#symbol-Logger) from `logger`.
+It uses [`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write)) from `august.io`. It uses [`Logger`](logger.md#symbol-Logger) from `logger`.
 
 ::::
 

package/docs/examples/developer-workflow/logging/logger.md

@@ -64,11 +64,11 @@ Receives a message describing an application operation.
 
 #### `Logger.log` · [source](logger.md#code) {#symbol-Logger.log}
 
-It takes `message` as a string (Text to write). It gets `console` ([`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It can call [`Console.write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
+It takes `message` as a string (Text to write). It gets `console` ([`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It can call [`Console.write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
 ### Dependencies
 
-It uses [`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write)) from `august.io`.
+It uses [`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write)) from `august.io`.
 
 ::::
 

package/docs/examples/developer-workflow/main.md

@@ -99,7 +99,7 @@ catch IndexError error {
 
 ### Providers
 
-`Console` is provided by [`SystemConsole`](dependencies/august/0.20.1/io/contracts.md#symbol-SystemConsole). The same instance is shared. `Logger` is provided by [`ConsoleLogger`](logging/console.md#symbol-ConsoleLogger). The same instance is shared.
+`Console` is provided by [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole). The same instance is shared. `Logger` is provided by [`ConsoleLogger`](logging/console.md#symbol-ConsoleLogger). The same instance is shared.
 
 ### Startup
 
@@ -111,7 +111,7 @@ It prints the value under `2` in `fruit`. It prints [`load`](calculator.md#symbo
 
 ### Dependencies
 
-It uses [`SystemConsole`](dependencies/august/0.20.1/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Calculator`](calculator.md#symbol-Calculator) ([`add`](calculator.md#symbol-Calculator.add)) and [`load`](calculator.md#symbol-load) from `calculator`. It uses [`ConsoleLogger`](logging/console.md#symbol-ConsoleLogger) from `logging`.
+It uses [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Calculator`](calculator.md#symbol-Calculator) ([`add`](calculator.md#symbol-Calculator.add)) and [`load`](calculator.md#symbol-load) from `calculator`. It uses [`ConsoleLogger`](logging/console.md#symbol-ConsoleLogger) from `logging`.
 
 Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 

package/docs/examples/errors-benchmark/index.md

@@ -0,0 +1,36 @@
+---
+title: "Checked-error benchmark"
+generated: true
+source: "benchmarks/errors"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Checked-error benchmark
+
+Interleave successful calls and caught checked failures.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+
+## Try this project
+
+[Download this project](/downloads/errors-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd errors-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)