@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/docs/native-packages.md

@@ -0,0 +1,179 @@
+# Native libraries as August packages
+
+Native locks keep a compiler selection for each host under `native.compilers`.
+A project can record macOS ARM64 and both GNU/Linux hosts without one build
+replacing another host's compiler or runtime pin. A frozen build requires the
+entry for its current host. Run `aug build --backend llvm` once on each new host
+before using `--frozen` there; cross-compilation is not supported.
+
+The LLVM preview lets an August package wrap a C ABI without exposing native
+pointers to application code. A package supplies August declarations, a checked
+binding descriptor, and prebuilt libraries. The compiler checks their labels,
+types, errors, and ownership before generating LLVM IR and a native executable.
+
+This is development work for `0.21.0`, not a capability of the published
+`0.20.1` CLI. Public release installation is being qualified. The first target is
+macOS 14 or later on Apple Silicon. LLVM is the default for ordinary projects
+and native packages. The C migration reference requires `--backend c` or
+`backend: c` in `main.yaml`; native ABI packages require LLVM.
+
+Linux x86-64 and ARM64 support is being qualified on Debian 12 and Ubuntu,
+with glibc 2.36 or later. Both architectures pass LLVM regression and installed
+CLI checks with measured library candidates. Their library artifacts are public;
+clean public-download consumer checks have passed independently on both architectures.
+Compiler publication remains a release gate.
+Musl and cross compilation are unsupported. A package declares its libc floor
+and C++ ABI in addition to its OS and architecture; August rejects an incompatible
+host before compiling the application.
+
+## Import a library
+
+The [PyTorch](https://github.com/GreenPandaStudios/aug-pytorch),
+[SQLite](https://github.com/GreenPandaStudios/aug-sqlite),
+[zlib](https://github.com/GreenPandaStudios/aug-zlib), and
+[BLAKE3](https://github.com/GreenPandaStudios/aug-blake3) repositories publish
+source and native preview archives for all three platforms: PyTorch `v0.1.4` and
+the other three packages `v0.1.3`. Their imports have passed using the packaged CLI,
+public downloads, and fresh caches on macOS ARM64 and both GNU/Linux architectures.
+The matching compiler release is still pending. The consumer gates passed in CI;
+subsequent compiler revisions must pass it again before publication.
+
+After the matching compiler preview is published, use the normal
+package commands. This example adds CPU LibTorch under a short name:
+
+```sh
+aug add https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4 --as pytorch
+aug run
+```
+
+The following program is an example for that preview:
+
+```text
+import Tensor and TensorError and tensor and add and sum from pytorch
+
+try:
+    own Tensor left = tensor(values=[1.0, 2.0, 3.0])
+    own Tensor right = tensor(values=[4.0, 5.0, 6.0])
+    own Tensor result = add(left, right)
+    print(value=sum(tensor=result)) // 21
+catch TensorError error:
+    print(value=error.message)
+```
+
+`own` makes each tensor's lifetime explicit. Leaving its scope releases the
+native tensor, including when a call fails. Reading a tensor lends it for the
+duration of the call. Passing it to an owned input transfers responsibility to
+the callee. Replacing an owned field releases its previous value immediately.
+
+SQLite, zlib, and Rust BLAKE3 use the same package path. The
+[package examples](native-package-examples.md) show their operations; the
+[implementation record](native-implementation.md) separates verified behavior
+from release and platform work still in progress.
+
+Read the complete projects with their compiled explanations:
+[PyTorch](examples/native-pytorch/index.md),
+[SQLite](examples/native-sqlite/index.md),
+[zlib](examples/native-zlib/index.md), and
+[Rust BLAKE3](examples/native-blake3/index.md). Each includes a same-file test and
+a downloadable project. Native dependency pages link to the exact binding
+descriptor, so ownership and native boundaries stay visible beside the code.
+
+## Check and generate bindings
+
+Binding maintainers can use the preview's `aug bind header` command. Supply a
+reviewed `native.abi.json` ownership contract and the adapter's C header. The
+command uses your explicitly selected Clang; it does not install a toolchain or
+run a package recipe.
+
+```sh
+aug bind header native/include/aug_zlib.h \
+  --contract native.abi.json \
+  --target aarch64-apple-darwin \
+  --clang /path/to/pinned/clang \
+  --output .aug-build/checked-bindings
+```
+
+For GNU/Linux, select `x86_64-unknown-linux-gnu` or
+`aarch64-unknown-linux-gnu` in the corresponding maintainer environment. Extra
+Clang include, macro and sysroot flags follow `--`. Consumers still need no
+Clang. Keep the maintainer compiler version pinned in your build recipe.
+
+The command checks physical function types, fixed-width integers, byte booleans,
+buffer lengths, output pointers, release signatures and the ABI error record's
+size, alignment and field offsets. It rejects unsigned results declared as
+August signed integers. Resource input pointers must match their release
+function, and mutable loans cannot use const pointers. It writes generated
+`src` declarations, the descriptor and `header-check.json` only after every
+check passes. Existing output directories are preserved.
+
+Review the generated imports and declarations, then copy them into the package
+beside its handwritten error types and safe API. The command does not invent an
+error class or public wrapper. Include the checked report in native build
+provenance and repeat the check whenever headers, compiler flags or descriptors
+change. The report records compiler, target, header digests and signatures.
+
+Ownership, allocator pairing, retention and thread behavior remain promises
+made by the binding author. A matching header cannot establish those promises;
+independent adapter tests must check them. C++ and Rust packages provide C
+adapter headers for this command. Templates, callbacks, variadic calls and
+aggregate values are outside the initial binding profile.
+
+## Installation and deployment
+
+`aug.lock.json` records the source revision, binding digest, selected native
+archive, compiler pack, and runtime identity. Archive downloads are bounded and
+SHA-256 checked. Extraction rejects links, traversal, duplicate paths, and
+unexpected files. Cached files are checked again before use. Package installation
+does not execute native recipes or npm lifecycle scripts.
+
+A failed download or extraction leaves no accepted artifact cache. Disk-full
+errors include the CLI's space-recovery guidance; they do not leave a partially
+installed library selected by a lockfile.
+
+Consumers need Node 24 and a supported OS, but do not install LLVM or Clang for
+this profile. August downloads its own pinned LLVM tools and runtime. A missing
+or incompatible artifact produces a diagnostic; it never starts a source build.
+Use `aug run --offline --frozen` after an online installation to require the
+recorded artifacts without downloading replacements.
+
+Public GitHub source downloads use HTTPS and do not require Git. If GitHub's
+shared API rate limit stops installation, retry later or set `AUG_GITHUB_TOKEN`
+to authenticate API reads. August sends this token only to `api.github.com`,
+rejects redirects, and never writes it to source caches or lockfiles.
+
+Keep the executable together with its adjacent `lib` and `share` directories.
+The libraries load relative to the executable. `share/august-native` preserves
+the selected packages' notices, provenance, and file manifests.
+
+## Author a binding
+
+Declare an opaque resource with `extern C resource Handle` in an ordinary module.
+Hover, `aug context` and the compiled specification show the native provider,
+supported targets, loan duration and release operation. The compiler checks the
+binding signature and ownership at August call sites. Input retention, thread
+behavior and exception containment are promises made by the native author; these
+tools do not prove the foreign implementation follows them. Context identifies
+native dependencies reached through resolved standalone calls and does not claim
+complete member-dispatch coverage.
+Its `native.abi.json` entry names a leaf release function. Extern declarations
+and descriptor entries must agree; application code imports safe August wrappers
+through `export.aug`. Calls to extern functions remain inside `unsafe`.
+
+The initial ABI uses fixed-width scalars, pointer-and-length inputs, copied
+buffers, opaque handles, and checked status errors. C++ wrappers catch exceptions
+and Rust exports contain panics before returning through C. Sharing LLVM does
+not make C++, Rust, and August layouts compatible.
+
+Binding maintainers build and test native artifacts with the recorded toolchain.
+Consumers receive those verified artifacts. Callback registration, retained
+loans, foreign threads, native struct layout, GPU tensors, and exporting August
+libraries have not been qualified. See the
+[architecture and backlog](native-interop-llvm-plan.md).
+
+Linux maintainers build on Debian 12 so newer hosts do not raise the artifact's
+glibc requirement. The compiler checks the declared minimum; maintainer builds
+inspect each binary's actual symbol-version requirements and dependency closure.
+C++ adapters keep their qualified C++ runtime with the artifact. Source builds
+use Clang, platform headers and Linux relocation tools explicitly, while Rust
+adapters also use their pinned Rust/Cargo toolchain. Consumer installation has
+no automatic source-build fallback.

package/docs/packages.md

@@ -13,7 +13,7 @@ cd hello-august
 aug run
 ```
 
-You need Node.js 24 or later, npm, and a C11 compiler. Repository packages also need Git. macOS and Linux are the tested platforms. [Docker](docker.md) and [Dev Containers](dev-containers.md) provide a Linux toolchain when you prefer to work in a container.
+The pending 0.21.0 release needs Node.js 24 or later and npm on macOS 14+ ARM64 or GNU/Linux x64/ARM64 with glibc 2.36+. August downloads a verified LLVM/runtime pack; native package consumers do not install a compiler or SDK. GitHub repository imports use the CLI's HTTPS transport without Git. Other Git servers require a local Git client. [Docker](docker.md) and [Dev Containers](dev-containers.md) provide a Linux workspace. The published 0.20.1 CLI still requires a C11 compiler.
 
 `aug run` finds `main.aug`, installs source dependencies declared by imports or `main.yaml`, checks the code, prepares the native libraries it needs, and compiles and starts the executable. Later runs reuse those dependencies. `aug check` and `aug spec` read the installed snapshot without fetching packages. Use `aug install` before those commands in a fresh project.
 
@@ -127,4 +127,4 @@ Install [AugScript](https://marketplace.visualstudio.com/items?itemName=augscrip
 
 The CLI tarball requires its matching core stdlib package. npm normally obtains it automatically. For an archive installation, install the matching CLI and stdlib tarballs together; optional web and crypto packages are regular source libraries.
 
-Native dependencies use `~/.cache/augscript/native/VERSION/PLATFORM-ARCH`. `AUG_NATIVE_HOME` selects another cache. `aug-native` can prepare a cache in advance; `aug run` prepares what the application needs. The [release process](releasing.md) documents toolchain publishing for contributors.
+Verified LLVM packs and native artifacts use `~/.cache/augscript/native-artifacts`, keyed by their archive hashes. `AUG_NATIVE_ARTIFACT_CACHE` selects another cache. Source, compiler, runtime, and platform selections remain in `aug.lock.json`. The C migration reference uses the older `AUG_NATIVE_HOME` source-build cache. The [native package guide](native-packages.md) covers ownership, platform requirements, and publishing; [release process](releasing.md) covers the compiler distribution.

package/docs/performance.md

@@ -2,13 +2,17 @@
 
 This page publishes measurements for specific August programs alongside C, Node, and Python versions. Read the graphs for a quick comparison, inspect each program below, and use the reproduction commands to measure work that resembles your application.
 
-The recorded suite used August 0.18.0 and native C output. The current compiler is 0.20.1; these graphs have not been remeasured for that release. A result for one workload and host does not establish a general speed advantage or production readiness. [Readiness](production-readiness.md) covers reliability and deployment evidence separately.
+The recorded suite uses the August 0.21.0 candidate and LLVM 23.1.2 native output. A result for one workload and host does not establish a general speed advantage or production readiness. [Readiness](production-readiness.md) covers reliability and deployment evidence separately.
+
+The [extended qualification](qualification-results.md) adds eight C comparisons for numeric, collection and application work. The [safety gyms](safety-gyms.md) exercise results, rejected operations, cleanup and memory checks separately. Each measured program has a downloadable project and a code/spec view in the [gallery](examples/index.md#measured-programs).
+
+The [DGX Spark results](dgx-spark.md) record a second physical ARM64 host, including all benchmark programs, safety gyms and real public native imports. Read each host's measurements separately.
 
 ## Read the graphs
 
 Execution and memory bars use **lower is better**. HTTP throughput uses **higher is better**. Read the workload name and units before comparing: a 20,000-entry map and a two-million-step CPU loop do different amounts of work. The execution panels have separate linear scales; compare implementations within a panel. Tables provide exact values and remain readable on a phone.
 
-All results below were recorded on September 29, 2026: Apple M5, macOS Darwin 25.6.0, ARM64, Apple Clang 21, Node 24.18.0, CPython 3.12.14. August and C use `-O2` without LTO. [Raw samples, checksums, build timings and environment](benchmark-results.json) are committed with this page.
+All results below were recorded on October 2, 2026 (UTC): Apple M5, macOS Darwin 25.6.0, ARM64, LLVM 23.1.2 for August, Apple Clang 21 for the C reference, Node 24.18.0, and CPython 3.12.14. August and C use `-O2` without LTO. [Raw samples, checksums, build timings and environment](benchmark-results.json) include the LLVM tool and runtime identities.
 
 ## Execution time
 
@@ -18,15 +22,15 @@ All results below were recorded on September 29, 2026: Apple M5, macOS Darwin 25
 
 | Workload | August | C | Node | Python |
 | --- | ---: | ---: | ---: | ---: |
-| Startup | 1.46 ms | 1.29 ms | 19.07 ms | 8.42 ms |
-| CPU · 2 million iterations | 7.24 ms | 8.17 ms | 30.22 ms | 194.98 ms |
-| Map + Set · 20,000 entries | 2.54 ms | 1.65 ms | 22.31 ms | 10.36 ms |
-| Map + Set · 200,000 entries | 15.10 ms | 6.38 ms | 38.33 ms | 26.44 ms |
-| JSON · 5,000 round trips | 6.92 ms | 2.01 ms | 20.84 ms | 19.20 ms |
+| Startup | 1.43 ms | 1.19 ms | 19.31 ms | 16.18 ms |
+| CPU · 2 million iterations | 7.74 ms | 8.38 ms | 30.64 ms | 252.62 ms |
+| Map + Set · 20,000 entries | 2.71 ms | 1.64 ms | 22.58 ms | 18.81 ms |
+| Map + Set · 200,000 entries | 16.81 ms | 6.31 ms | 37.96 ms | 40.36 ms |
+| JSON · 5,000 round trips | 7.23 ms | 1.94 ms | 21.16 ms | 31.84 ms |
 
 [benchmark-execution-end]: #
 
-Times include a fresh process's startup and exclude compilation: 3 warmups and 15 measured runs for each implementation, with the execution order rotated. Every run must produce the expected checksum. Node and Python start a new interpreter each time; these are batch timings, not warmed server-loop or steady-state JIT timings. The startup row helps make that cost visible; subtracting medians would not establish a new measured result.
+Times include a fresh process's startup and exclude compilation: 3 warmups and 60 measured runs for each implementation, with the execution order rotated. The measurement client runs outside the compiler process, and every executable must produce the expected checksum. Node and Python start a new interpreter each time; these are batch timings, not warmed server-loop or steady-state JIT timings. The startup row helps make that cost visible; subtracting medians would not establish a new measured result.
 
 The programs below are the actual benchmark sources. The suite checks their printed results against the C, Node and Python references on every run.
 
@@ -34,7 +38,7 @@ The C reference is tailored to these inputs: it preallocates integer tables and
 
 [benchmark-summary-start]: #
 
-The CPU program takes **7.24 ms** in August and **8.17 ms** in C on this host. The large-collection program takes **15.10 ms** in August. These are measurements of the shown programs, not guarantees for other applications. JSON batch time includes interpreter startup for Node and Python; it does not establish a universal JSON-throughput advantage.
+The CPU program takes **7.74 ms** in August and **8.38 ms** in C on this host. The large-collection program takes **16.81 ms** in August. These are measurements of the shown programs, not guarantees for other applications. JSON batch time includes interpreter startup for Node and Python; it does not establish a universal JSON-throughput advantage.
 
 [benchmark-summary-end]: #
 
@@ -47,6 +51,7 @@ Save this as `main.aug`. Its result is `7`; the measurement includes starting an
 **main.aug**
 
 ```aug project=benchmark-startup file=main.aug
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 print(value=7)
 ```
 
@@ -62,6 +67,7 @@ This loop performs two million dependent integer steps. Its result must be `8196
 **main.aug**
 
 ```aug project=benchmark-cpu file=main.aug
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 // A loop-carried dependency prevents removal of the computation.
 int state = 123
 int index = 0
@@ -84,6 +90,7 @@ This creates a Map and Set, inserts 20,000 values, checks membership, and sums v
 **main.aug**
 
 ```aug project=benchmark-collections file=main.aug
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 own Map<int, int> values = {}
 own Set<int> unique = {}
 int index = 0
@@ -111,13 +118,15 @@ These two files belong in one folder. The program parses JSON, reads a typed rec
 **data.aug**
 
 ```aug project=benchmark-json file=data.aug
+// aug-spec: "data.aug.md" explains this file. Read it before changes; refresh with aug spec.
 record Payload(int id, string message, List<int> values)
 ```
 
 **main.aug**
 
 ```aug project=benchmark-json file=main.aug
-import parse from "https://github.com/GreenPandaStudios/augscript/src/stdlib/json#v0.19.0"
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import parse from json
 import Payload from data
 int checksum = 0
 int index = 0
@@ -133,6 +142,15 @@ catch JsonError error:
     exit(status=1)
 ```
 
+**main.yaml**
+
+```yaml project=benchmark-json file=main.yaml
+
+
+packages:
+  json: "https://github.com/GreenPandaStudios/augscript/src/stdlib/json#v0.19.0"
+```
+
 
 [benchmark-source-json-end]: #
 
@@ -144,13 +162,13 @@ catch JsonError error:
 
 | Clients | August req/sec | Node req/sec | August p95 latency | Node p95 latency |
 | ---: | ---: | ---: | ---: | ---: |
-| 1 | 23,526 | 25,580 | 0.05 ms | 0.04 ms |
-| 16 | 73,370 | 69,166 | 0.37 ms | 0.40 ms |
-| 64 | 65,365 | 69,260 | 1.74 ms | 1.32 ms |
+| 1 | 21,046 | 23,679 | 0.06 ms | 0.05 ms |
+| 16 | 58,708 | 55,557 | 0.46 ms | 0.49 ms |
+| 64 | 54,436 | 51,730 | 2.08 ms | 1.94 ms |
 
 [benchmark-http-end]: #
 
-A real August `GET /bench` endpoint returns a newly constructed typed JSON record. The Node reference constructs and serializes the same response. Both run on loopback with HTTP/1.1 keep-alive, 1,000 warmup requests and three fresh-server rounds of 5,000 measured requests per concurrency level. Every response must have status 200, JSON content type, and the exact expected data. The measured runs had zero errors. p95 is the median of the three per-round p95 latencies; graph error bars show observed throughput min/max, not confidence intervals.
+A real August `GET /bench` endpoint returns a newly constructed typed JSON record. The Node reference constructs and serializes the same response. Both run on loopback with HTTP/1.1 keep-alive, 1,000 warmup requests and five fresh-server rounds of 5,000 measured requests per concurrency level. Every response must have status 200, JSON content type, and the exact expected data. The measured runs had zero errors. p95 is the median of the five per-round p95 latencies; graph error bars show observed throughput min/max, not confidence intervals.
 
 The Node load generator runs on the same machine and consumes CPU. This closed-loop test has no TLS, authentication, logging, database, outbound network calls or slow clients. Its numbers are endpoint microbenchmark throughput, not a supported production capacity or service-level guarantee. HTTP/2, HTTP/3 and streaming are not benchmarked here.
 
@@ -165,14 +183,16 @@ Place these files in one folder. Every request constructs a `Reply` and returns
 **routes.aug**
 
 ```aug project=benchmark-http file=routes.aug
+// aug-spec: "routes.aug.md" explains this file. Read it before changes; refresh with aug spec.
 record Reply(int id, string message)
-endpoint GET "/bench" as reply() returns Reply:
+endpoint GET "/bench" as reply() :
     return Reply(id=7, message="hello")
 ```
 
 **main.aug**
 
 ```aug project=benchmark-http file=main.aug
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import reply from routes
 serve reply on port 0
 ```
@@ -267,7 +287,8 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1
     for (let i = 0; i < rounds; i++) {
       await httpLoad(url, concurrency, warmup, expected);
       const result = await httpLoad(url, concurrency, requests, expected);
-      delete result.latencyMs.samples; results.push(result);
+      if(!process.argv.includes('--raw-samples'))delete result.latencyMs.samples;
+      results.push(result);
     }
     const measured = statistics(results.map(result => result.requestsPerSecond));
     console.log(JSON.stringify({url, concurrency, warmup, rounds:results, requestsPerSecond:measured}, null, 2));
@@ -287,11 +308,11 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1
 
 | Workload | August | C | Node | Python |
 | --- | ---: | ---: | ---: | ---: |
-| Startup | 1.3 MiB | 1.4 MiB | 46.0 MiB | 15.1 MiB |
-| CPU · 2 million iterations | 1.3 MiB | 1.4 MiB | 52.2 MiB | 15.1 MiB |
-| Map + Set · 20,000 entries | 4.5 MiB | 4.4 MiB | 57.0 MiB | 20.2 MiB |
-| Map + Set · 200,000 entries | 34.2 MiB | 25.4 MiB | 91.1 MiB | 62.1 MiB |
-| JSON · 5,000 round trips | 1.8 MiB | 1.5 MiB | 47.4 MiB | 16.2 MiB |
+| Startup | 1.3 MiB | 1.3 MiB | 46.0 MiB | 8.4 MiB |
+| CPU · 2 million iterations | 1.3 MiB | 1.3 MiB | 52.2 MiB | 8.4 MiB |
+| Map + Set · 20,000 entries | 4.7 MiB | 4.4 MiB | 56.9 MiB | 13.2 MiB |
+| Map + Set · 200,000 entries | 36.8 MiB | 25.4 MiB | 91.1 MiB | 55.3 MiB |
+| JSON · 5,000 round trips | 1.8 MiB | 1.5 MiB | 47.4 MiB | 9.7 MiB |
 
 [benchmark-memory-end]: #
 
@@ -299,7 +320,7 @@ These are medians of three separate peak-RSS measurements through `/usr/bin/time
 
 ## Before and after
 
-The same August programs and measurement settings were run on this machine before and after the performance work. Shorter bars are faster for execution time; taller points are faster for HTTP. This compares observed application performance. [Earlier measurement summaries](benchmark-baseline.json) preserve the baseline.
+The earlier September 29 measurements and current LLVM measurements use the same August programs on this host. Versions and backends differ; the earlier HTTP run used three rounds and the current run uses five. The current suite also isolates each load client in a fresh process. This is a historical comparison of observed performance, not a controlled estimate of one compiler change. Shorter bars are faster for execution time; taller points are faster for HTTP. [Earlier measurement summaries](benchmark-baseline.json) preserve the baseline.
 
 ![August execution time and HTTP throughput before and after the performance update, using the same workloads.](./assets/benchmarks/improvements.svg)
 
@@ -307,13 +328,13 @@ The same August programs and measurement settings were run on this machine befor
 
 | August workload | Before | Current | Current relative to before |
 | --- | ---: | ---: | ---: |
-| CPU · 2 million iterations | 36.65 ms | 7.24 ms | 5.06× faster |
-| Map + Set · 20,000 entries | 4.68 ms | 2.54 ms | 1.84× faster |
-| Map + Set · 200,000 entries | 47.90 ms | 15.10 ms | 3.17× faster |
-| HTTP · 1 clients | 25,273 req/sec | 23,526 req/sec | 0.93× throughput |
-| HTTP · 16 clients | 62,719 req/sec | 73,370 req/sec | 1.17× throughput |
-| HTTP · 64 clients | 30,693 req/sec | 65,365 req/sec | 2.13× throughput |
-| Map + Set · 200k peak memory | 61.9 MiB | 34.2 MiB | 45% less |
+| CPU · 2 million iterations | 36.65 ms | 7.74 ms | 4.73× faster |
+| Map + Set · 20,000 entries | 4.68 ms | 2.71 ms | 1.72× faster |
+| Map + Set · 200,000 entries | 47.90 ms | 16.81 ms | 2.85× faster |
+| HTTP · 1 clients | 25,273 req/sec | 21,046 req/sec | 0.83× throughput |
+| HTTP · 16 clients | 62,719 req/sec | 58,708 req/sec | 0.94× throughput |
+| HTTP · 64 clients | 30,693 req/sec | 54,436 req/sec | 1.77× throughput |
+| Map + Set · 200k peak memory | 61.9 MiB | 36.8 MiB | 40% less |
 
 [benchmark-improvements-end]: #
 

package/docs/production-readiness.md

@@ -12,6 +12,8 @@ The same-app [OpenID Connect example](examples/oidc-login/index.md) proves integ
 
 ## Dependencies and licenses
 
+The [safety gyms](safety-gyms.md) now collect generated LLVM cases, rejected contracts, behavioral mutations and the larger runtime circuits in one replayable report. [Recorded qualification](qualification-results.md) shows the actual execution counts and skipped checks. The expanded performance suite measures eight further programs against C. These checks strengthen the release evidence without establishing universal safety or speed.
+
 The CLI uses its matching core August library and `tar` 7.5.22 for registry archive extraction. The extension bundles that parser and its JavaScript dependencies. The VS Code extension's npm audit currently reports zero advisories. The wiki build uses VitePress and a pinned Vite override; run `npm audit` before each release. npm audit only covers npm packages and cannot certify native code or deployment configuration.
 
 | Dependency | Role | License from upstream | Distribution consideration |
@@ -31,10 +33,18 @@ The exact versions, archive URLs, and SHA-256 values are in [`native-dependencie
 
 ## Release gates still open
 
+The [LLVM/native candidate](native-implementation.md) supports real repository
+imports of CPU LibTorch, SQLite, zlib and Rust BLAKE3 on macOS ARM64 and
+GNU/Linux x86-64/ARM64 with glibc 2.36+. Installed CLI checks cover public
+downloads, exact locks, offline reuse, relocated bundles and finite ownership
+cases without native tools or development headers. Language parity, DWARF and
+core sanitizers are implemented. The 0.21.0 candidate selects LLVM by default;
+its updated platform gates and public compiler release remain pending.
+
 - **Platform support:** the full pinned web/crypto bootstrap passes on macOS ARM and Linux ARM. [Docker build/run bases](docker.md) run core, web, and crypto programs on Linux. Linux x86-64 runs in CI; other platforms remain unverified.
 - **Concurrency and ownership:** tasks use one OS thread. The [conformance suite](language-conformance.md) exercises injected captures, mutation after a child starts inside `borrow`, owned `Shared<T>` cleanup, branch joins, cancellation, and the public `Task<T>` error contract. A 1.0 support claim still depends on the platform, distribution, and compatibility gates.
 - **Security and reliability:** HTTP and OIDC need broad protocol conformance, durable credentials and keys, rotation, long-running load tests, and deployment guidance. The [gap ledger](web-library-gaps.md) records the precise work.
 - **Package and ABI stability:** the [matching 0.19.0 npm packages](packages.md#npm-registry) are published and their core starter workflow is verified. Reproducible releases, compatibility policy, and native adapter ABI still need stable release gates.
 - **Operational behavior:** failure handling, cancellation, instrumentation, platform builds, and resource ceilings need repeated CI and field testing.
 
-For a trial deployment, pin the compiler and native lock, run the project's tests and `aug spec --check`, review the generated C/native linker inputs, and validate the executable under your own load and failure conditions. Track the [gap ledger](web-library-gaps.md) before promising production service levels.
+For a trial deployment, pin the compiler and native lock, run the project's tests and `aug spec --check`, review its native artifact and deployment inputs, and validate the executable under your own load and failure conditions. Track the [gap ledger](web-library-gaps.md) before promising production service levels.

package/docs/qualification-results.md

@@ -0,0 +1,66 @@
+---
+generatedBy: scripts/render-qualification.mjs
+---
+# Extended performance and safety results
+
+These results cover the August 0.21.0 candidate on **Apple M5**, darwin 25.6.0 arm64, recorded 2026-10-02. August uses LLVM 23.1.2. Every measured result matched its required output. They do not establish a general C-speed or production-safety guarantee.
+
+## Eight more C comparisons
+
+::: benchmark-chart
+
+![Median August and C execution times for eight programs. Each panel has its own scale; lower is better.](assets/benchmarks/kernels.svg)
+
+![Median August and C execution times, arranged vertically for smaller screens. Lower is better.](assets/benchmarks/kernels-mobile.svg)
+
+:::
+
+Each value is the median of 30 fresh executable processes after 3 warmups. Order rotates within a separate measurement process. Timings include startup and exclude compilation. Both implementations use O2 without LTO or fast-math. [Raw samples, build times and code sizes](kernel-results.json) also include the same August programs compiled through the C migration backend.
+
+| Program and code/spec | Work per run | August | C | August / C |
+| --- | ---: | ---: | ---: | ---: |
+| [Floating-point loop](examples/float-benchmark/main.md) | 1,000,000 | 2.29 ms | 1.69 ms | 1.36 |
+| [Labeled function calls](examples/calls-benchmark/main.md) | 200,000 | 2.34 ms | 1.77 ms | 1.33 |
+| [List traversal](examples/list-benchmark/main.md) | 100,000 | 1.99 ms | 1.20 ms | 1.66 |
+| [String processing](examples/strings-benchmark/main.md) | 20,000 | 9.30 ms | 2.67 ms | 3.48 |
+| [Map deletion and refill](examples/map-churn-benchmark/main.md) | 4,000 | 4.78 ms | 4.18 ms | 1.14 |
+| [Checked failures](examples/errors-benchmark/main.md) | 20,000 | 1.37 ms | 1.13 ms | 1.21 |
+| [Record allocation](examples/records-benchmark/main.md) | 50,000 | 9.40 ms | 2.01 ms | 4.66 |
+| [Task scheduling](examples/tasks-benchmark/main.md) | 2,000 | 3.89 ms | 1.19 ms | 3.27 |
+
+Ratios above 1 mean August took longer. The C references use concrete values and explicit cleanup. Their ordered map uses linear searches and their task case makes sequential calls; it does not pay for a scheduler. The string reference copies each part, while August also creates managed strings and a list. Records retain individually allocated values in both programs, with different layouts and lifetime tracking. These are visible differences, not interchangeable implementations. [Read the C references](https://github.com/GreenPandaStudios/augscript/blob/main/benchmarks/kernels.c) before drawing conclusions.
+
+The float program checks its exact accumulated binary-fraction result. The call loop carries each result into the next call. Lists and records retain data and read it afterward. Map deletion checks reinsertion order as well as values. Error cases verify both the sum and number of failures; task cases verify the joined sum. Their [downloadable projects](examples/index.md#measured-programs) show code beside compiled specs in either indentation or braces style.
+
+## Safety qualification
+
+Seed **877966**, generator version **1**, 256 generated vectors per exercise plus fixed edge cases. Both development and optimized LLVM builds ran the corpus.
+
+| Exercise | Vectors executed across both builds | Result |
+| --- | ---: | --- |
+| arithmetic | 516 | Passed; both behavioral mutations detected |
+| floating-point | 520 | Passed; both behavioral mutations detected |
+| collections | 516 | Passed; both behavioral mutations detected |
+| control-flow | 516 | Passed; both behavioral mutations detected |
+| checked-bounds | 520 | Passed; both behavioral mutations detected |
+| cleanup | 512 | Passed; both behavioral mutations detected |
+| tasks | 512 | Passed; both behavioral mutations detected |
+
+The suite executed **3612 generated/edge-case checks**, rejected **8 forbidden contracts**, and detected **14 valid behavioral mutants**. Each mutant compiled and ran safely; its wrong result or cleanup count differed from the independent oracle.
+
+| Additional circuit | Executed tests | Skipped tests | Result |
+| --- | ---: | ---: | --- |
+| source-mutations | 3 | 0 | passed |
+| ownership-concurrency | 53 | 0 | passed |
+| native-boundaries | 2 | 0 | passed |
+| package-integrity | 19 | 0 | passed |
+| http-boundaries | 6 | 0 | passed |
+| sanitizers | 4 instrumented programs + LLVM negative control | 0 | passed |
+
+[The full report](gym-results.json) includes original and faulty source units, inputs, expected and actual results, cleanup counts, compiler source identity and commands. Source mutation includes 5,000 parser cases and 1,000 checker cases. Core sanitizers instrument August LLVM accesses and the C runtime; they do not instrument the interiors of prebuilt foreign libraries or establish a whole-process leak proof.
+
+The [safety gym guide](safety-gyms.md) explains each gate and its limits. [Contributor commands](contributing-benchmarks.md) reproduce these reports or explore another seed. New-platform CI reports remain separate until that target completes qualification.
+
+## Source identity
+
+Both reports use source SHA-256 `23c9155410c0af115173e99c583e86374df5b83e22d9ce82aeabeb19405384a0`. This fingerprints compiler, runtime, native platform inputs, package contracts, configuration, dependencies, test fixtures, generators and measured programs. Recorded evidence remains tied to that snapshot; a later change requires a new run.

package/docs/reference.md

@@ -116,6 +116,19 @@ Constraints name interfaces. Multiple constraints use `and`. Only interfaces dec
 
 A class starts with its name and ends its header with `implements Interface`. There is no `class` or `function` prefix and no class inheritance. Interfaces can extend several interfaces and supply default methods; conflicting inherited defaults require an explicit override. Interfaces have methods and no fields.
 
+An initializer can reject construction with a checked error. Declare that error
+before `implements`, as in `Session(own Handle handle) unless SessionError
+implements ActiveSession`. Callers catch or propagate the error. If construction
+fails after ownership transfers, August releases the partial object and its owned
+fields before the error reaches the caller. `drop` runs only on a successfully
+constructed object. Partial cleanup releases
+initialized owned fields and keeps the constructor error; it does not run `drop`
+against fields that might not have been initialized. Class constructors require a written
+`unless` contract; record validation can infer its failures.
+Fallible class constructors currently require explicit construction. They cannot
+be DI binding targets; startup and injected-construction failure handling need a
+separate contract before that form is supported.
+
 Header inputs become fields. Fields are read-only after initialization unless marked `mutable`. Public names grant access; names starting with `_` keep storage private. Separate a public constructor label from private storage with `int initial to _count`. The shorthand `int _count` exposes the input label `count`.
 
 ```aug project=state-guide file=main.aug
@@ -296,6 +309,17 @@ An error satisfies Error. A body infers escaping errors. A bodyless signature or
 
 `start` evaluates its receiver and arguments immediately; their errors belong to the scheduling statement. The scheduled operation's errors belong to a `wait for` or its owning scope's implicit join. Unobserved sibling failures can reach any wait in that group. Grouped waits observe every selected child, including cancellation cleanup, and rethrow the first failure. A helper awaiting a `Task<T>` parameter declares or handles `Error`, since that public type does not specify a narrower error contract yet.
 
+A task can take an owned input. Scheduling transfers cleanup responsibility to
+the child, including when cancellation occurs before its function runs. A task
+cannot return an `own` value: `Task<T>` has no owned-result transfer contract.
+Create and release resources inside the task, then return immutable data.
+
+Owned locals in a `try` or `catch` body are released when that body exits, before
+its `always` block runs. This order applies to normal execution, returns and
+errors. Values owned by the enclosing function remain live until that function
+exits. Cleanup suspends pending errors and cancellation while a `drop` method
+runs, then restores them.
+
 An error already leaving the parent remains the reported error if cancelling a child causes its cleanup to fail. `always` cleanup still runs for that child. A `return` from a scope joins its children before the caller receives the result.
 
 ```aug project=errors-guide file=main.aug