@greenpandastudios/aug-cli 0.19.0 → 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

@@ -1,6 +1,12 @@
-# AugScript diagnostics and fixes
+# Diagnostics and fixes
 
-Diagnostics include a code, source location, and expected/actual contract where relevant. VS Code shows them while editing, with hover guidance and lightbulb actions. Fixes are precise edits; they are offered only where the compiler has enough information. Warnings do not prevent a build.
+Start with the diagnostic's file, line, and message. The code identifies the rule that failed; the tables below explain likely remedies. VS Code shows the same diagnostics while you edit, with hover help and lightbulb actions where the compiler can offer a precise change. Warnings do not prevent a build.
+
+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 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.
 
 ## Syntax and data
 
@@ -40,7 +46,7 @@ Both braces and indentation are accepted. The formatter uses main.yaml preferenc
 
 ### EFFECT
 
-Callables are pure by default. Declare `changes self` for state transitions or `changes input` for an owned/borrowed input. Receive I/O capabilities through resolve headers and declare `uses dependency.operation`. Callers and interface contracts include every effective effect, including layers.
+Bodies infer `changes self` for state transitions and `changes input` for borrowed inputs. Bodyless interfaces declare permitted changes. Receive I/O capabilities through dependency headers. Executable bodies infer capability operations, mutations, and escaping checked errors. Bodyless interfaces declare their allowed effects with `uses dependency.operation`; explicit clauses remain checked bounds. Calls and interceptor layers must fit the effective contract.
 
 Public fields and managed inputs grant reading. Mark local storage mutable when it needs initialization-independent changes. Constructors are pure; move startup effects into a named method. drop performs only local cleanup and cannot acquire effects/errors through interceptors.
 
@@ -64,7 +70,7 @@ A child task keeps its captured objects available until `wait for` or its scope
 
 ### THROWS
 
-A checked error lacks a compatible catch or unless declaration. The language uses `unless`; THROWS is the diagnostic identifier retained for tooling.
+A checked error reaches main without a compatible catch, or exceeds an explicit unless bound. Bodies infer escaping errors when unless is omitted. The language uses `unless`; THROWS is the diagnostic identifier retained for tooling.
 
 **Propagate with unless** adds the specific error to the enclosing contract. At composition statements, **Catch and report the failure** creates a visible recovery template. Choose domain recovery deliberately; no fix silently discards an error.
 
@@ -91,7 +97,11 @@ Next exists only inside around. `next()` forwards original inputs; `next(y=value
 | TEST | Put a class/function suite beside its declaration. Unique groups/cases; bindings before setup before cases. Check row arity/types and execute a bool assertion in each case. |
 | DOC | @param labels, value-return tags, and error tags must match the effective signature. Unknown tags are errors. Missing public docs become warnings only when enabled. |
 | CONFIG | main.yaml uses the supported keys and simple YAML lists. Unknown/duplicate keys and invalid values fail during check. |
-| FFI | Use supported boundary types, matching C widths, labeled inputs, unsafe, and uses C.function in callable contracts. |
+| FFI | Use supported boundary types, matching C widths, labeled inputs, unsafe, and an inferred or declared C.function effect. |
 | NATIVE | A C compiler error mapped to its .aug file and line. Fix the boundary declaration or linker configuration; inspect emit-c for generated details. |
 
 See [testing](testing.md) and [native tooling](tooling.md) for executable examples and exact limits.
+
+## INFERENCE: add a type anchor
+
+The compiler cannot infer a result when recursive calls have no concrete return evidence, or when generic contracts keep expanding. State a finite `returns T`, `uses`, or `unless` contract at that boundary. Empty collections also need a contextual item type. This does not require repeating contracts on ordinary bodies.

package/docs/docker.md

@@ -1,23 +1,67 @@
-# Docker build and run images
+# Build and deploy with Docker
 
-The repository supplies two base images. 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 the matching native shared libraries and CA certificates. It runs a compiled August executable as an unprivileged user. Build the run image after the build image so both use the same native dependency build.
+Compile an August application in a Linux build container, then deploy its executable in a separate runtime image. You need Docker with a running Linux engine and a POSIX shell for these commands. The application does not need Node.js or a compiler in its deployed container. For editing and testing inside VS Code, use [a Dev Container](dev-containers.md).
 
-Build the images from the repository root:
+## Prepare the toolchain images
+
+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. Pin `AUG_VERSION` to the version used by your application:
+
+```dockerfile
+FROM node:24-bookworm
+ARG AUG_VERSION=0.21.0
+RUN apt-get update \
+    && 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}
+WORKDIR /workspace
+ENTRYPOINT ["aug"]
+CMD ["--help"]
+```
+
+Save this as `Dockerfile.run` beside it. Each application supplies its own `lib` and `share` directories beside the executable:
+
+```dockerfile
+FROM debian:bookworm-slim
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates zlib1g \
+    && rm -rf /var/lib/apt/lists/*
+RUN groupadd --system august \
+    && useradd --system --gid august --home-dir /app august
+WORKDIR /app
+USER august
+ENTRYPOINT ["/app/program"]
+```
+
+Build them in that order:
 
 ```sh
-docker build -f docker/Dockerfile.build -t augscript/build:local .
-docker build -f docker/Dockerfile.run -t augscript/run:local .
-docker build -f docker/Dockerfile.crypto-smoke -t augscript/crypto-smoke:local .
-docker run --rm augscript/crypto-smoke:local
-docker build -f docker/Dockerfile.web-smoke -t augscript/web-smoke:local .
-docker run --rm -p 127.0.0.1:8080:8080 augscript/web-smoke:local
+docker build -f Dockerfile.build -t augscript/build:local .
+docker build -f Dockerfile.run -t augscript/run:local .
 ```
 
-Create a project with `aug init my-app`, then compile it for Linux. The mount is writable because `aug build` writes `.aug-build` and generated specifications into the project. The following commands assume your Docker engine can bind-mount your working directory:
+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
+
+Create your application with the [npx starter](getting-started.md) or download a [complete project](examples/index.md), then compile it for Linux. The mount is writable because `aug build` writes `.aug-build` and generated specifications into the project. Run the commands below from the parent of `my-app`.
+
+Keep the project in a directory shared with your Docker engine. If Docker reports that the bind source path does not exist, check the engine's file-sharing settings. A remote engine cannot mount a folder that exists only on your client machine; see [bind mount constraints](https://docs.docker.com/engine/storage/bind-mounts/#considerations-and-constraints).
 
 ```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
 ```
@@ -30,6 +74,123 @@ docker run --rm \
   augscript/run:local
 ```
 
-The crypto smoke command prints the SHA-256 digest of `abc`. The web smoke image serves `GET /health` on port 8080 and returns `{"status":"ok"}`. The run image uses Debian bookworm's C runtime; a binary built with this build image uses the matching base distribution. The run image has no shell command in its entry point and contains no compiler, source, package manager, or application secrets. Supply environment, network, ports, and data mounts for your application when needed. These images are source recipes, not published registry tags.
+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
+
+Start a project using Node.js 24 and npm on your host:
+
+```sh
+npm install --global @greenpandastudios/aug-cli@next
+aug init my-api
+cd my-api
+```
+
+Replace `main.aug` and add `endpoints.aug`. The starter's unused greeting module can remain. This service has one endpoint that returns a record as JSON.
+
+**main.aug**
+
+```aug project=docker-http file=main.aug
+import health from endpoints
+
+serve health on port 8080
+```
+
+**endpoints.aug**
+
+```aug project=docker-http file=endpoints.aug
+record Health(string status)
+
+/** Confirm that the HTTP handler can answer a request. */
+endpoint GET "/health" as health() returns Health:
+    return Health(status="ok")
+
+test endpoint health client:
+    when health_checks:
+        it answers_successfully:
+            response = client.request(method="GET", path="/health")
+            assert(condition=response.status == 200)
+```
+
+Save `main.yaml` beside `main.aug`:
+
+```yaml
+optimization: release
+web:
+  host: 0.0.0.0
+```
+
+`web.host` must accept connections through the container's network interface. August's default, `127.0.0.1`, only accepts connections inside that container. The port comes from the `serve` statement; `main.yaml` selects the listening address and release compilation.
+
+Save this `Dockerfile` in `my-api`. Docker's [multi-stage build](https://docs.docker.com/build/building/multi-stage/) copies the compiled executable into the runtime image:
+
+```dockerfile
+FROM augscript/build:local AS build
+COPY . /workspace
+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/deploy/ /app/
+```
+
+Save `.dockerignore` in the same folder:
+
+```text
+.git
+.aug-build
+.aug-native
+.aug-packages
+node_modules
+.devcontainer
+.env
+.env.*
+*.key
+*.pem
+```
+
+Keep credentials out of the build context. Mount runtime files at the paths your application uses. The compiler reads `main.yaml` while building; environment variables configure your application only when its code reads them. If your application imports source packages, commit its manifest and `aug.lock.json`, then add `RUN aug install /workspace --frozen` before the test/build step. [Frozen installs](packages.md#reproducible-builds) restore the locked dependency graph; include local package sources in the build context when the manifest references them.
+
+Build and start your application image. The build runs the endpoint test before compiling. Keep your terminal in `my-api`:
+
+```sh
+docker build -t my-api:0.1.0 .
+docker run --detach --name my-api --init \
+  --restart unless-stopped \
+  --publish 127.0.0.1:8080:8080 \
+  my-api:0.1.0
+curl --fail http://127.0.0.1:8080/health
+```
+
+The test passes, and the HTTP request returns `{"status":"ok"}`. The published port is available on the Docker host's loopback address. Change the mapping deliberately if clients must connect directly from other hosts; omitting `127.0.0.1` publishes on all host interfaces. See [Docker's port publishing guide](https://docs.docker.com/engine/network/port-publishing/).
+
+Inspect output and stop this deployment with:
+
+```sh
+docker logs my-api
+docker stop my-api
+docker rm my-api
+```
+
+## Move the image to a server
+
+Tag and push the **application** image to your registry. Replace `registry.example.com/team` with your registry and namespace, and sign in using that registry's instructions:
+
+```sh
+docker tag my-api:0.1.0 registry.example.com/team/my-api:0.1.0
+docker push registry.example.com/team/my-api:0.1.0
+```
+
+On a Linux Docker server with access to that registry, pull and run it:
+
+```sh
+docker pull registry.example.com/team/my-api:0.1.0
+docker run --detach --name my-api --init \
+  --restart unless-stopped \
+  --publish 127.0.0.1:8080:8080 \
+  registry.example.com/team/my-api:0.1.0
+```
+
+Place a TLS reverse proxy on that server in front of `127.0.0.1:8080`, or configure the application's [native TLS](web.md#openapi-configuration). For native TLS, use stable absolute container paths for the certificate and private key in `main.yaml`, then mount those files at the same paths when starting the container. Build for the server's CPU architecture: an ARM64 image does not become an x86-64 executable when pushed. These recipes build for the Docker engine's default platform; run the build on the target architecture or use a separately verified cross-platform build setup.
 
-For a reproducible image build without a host bind mount, use a multistage Dockerfile: start with `FROM augscript/build:local AS build`, copy the application into `/workspace`, run `aug build /workspace --out /tmp/program`, then start with `FROM augscript/run:local` and copy `/tmp/program` to `/app/program` with `--chown=august:august`. The repository's [`Dockerfile.smoke`](../docker/Dockerfile.smoke) exercises this pattern with the generated starter.
+Pin the CLI version and retain the application image digest for each deployment. The base tags and Debian package versions can change; use reviewed base-image digests and controlled dependency updates when reproducing a release. Redistributed native libraries also have [license and notice obligations](production-readiness.md#dependencies-and-licenses). August remains experimental; use the [readiness review](production-readiness.md) when assessing a trial deployment.

package/docs/editor.md

@@ -0,0 +1,35 @@
+# Write August in VS Code
+
+Install the matching [AugScript extension](packages.md#vs-code), open the project folder, and start in `main.aug`. The editor reads the same checked contracts as the CLI, including unsaved changes. Install source dependencies with `aug run` or `aug install` so their declarations and documentation are available locally.
+
+## Complete a call
+
+Type part of a function or method name and choose a completion. The editor inserts its labeled inputs and places the cursor at the first value. Press Tab to move through the values. Injected `resolve` inputs are supplied by DI and do not appear as arguments you must fill in.
+
+For a function such as `total(int price, int quantity)`, completion inserts a call shaped like `total(price=0, quantity=0)`. The numbers are editable placeholders. Signature help describes each input while you type. If a local value has the same name as its input, you can use August's labeled shorthand, such as `total(price, quantity)`.
+
+Public declarations from nearby modules and installed packages also appear in completion. Choosing one can add its import. Imports follow `export.aug`; private names and unexported declarations stay out of the suggestions.
+
+## Start a declaration or test
+
+Type `record`, `interface`, `implementation`, or `method` for a declaration template. `test`, `testclass`, and `testendpoint` supply same-file tests. `endpointget`, `endpointpost`, `endpointpatch`, and `endpointdelete` supply route templates. Other templates cover imports, exports, conditions, errors, borrows, tasks, locks, interceptors, and comments.
+
+The completion provider follows `block_style` and `indentation` in `main.yaml`. Templates are starting points: replace their names, values, and bodies before running the program. The extension also supplies VS Code snippets and enables Tab completion for August files.
+
+## Understand a contract
+
+Hover over a declaration, a call, a keyword, or a built-in operation. Help includes Javadoc when it is present. Ctrl-click, or Cmd-click on macOS, opens the declaration. In an import, clicking `from` opens the sibling file or the package's `export.aug`.
+
+Contract hints show inferred return types, mutation, capabilities, and checked errors beside executable headers. They are display text; saving or formatting does not add them to the source. A tooltip expands long contracts. Set `augscript.inferredContractHints` to false to hide them. Bodyless interfaces and foreign declarations still state their contracts in code.
+
+## Fix a diagnostic
+
+Place the cursor on an error and open the lightbulb with Ctrl+. or Cmd+.. The editor offers fixes it can derive from the checked code: importing a visible declaration, correcting a nearby name or input label, expanding a wildcard import, adding a required method, or containing a mutable or native operation.
+
+Review the edit before accepting it. A suggested name can be plausible without being the name you intended. After a change, run `aug check`, your tests, and `aug spec` to refresh the neighboring explanation.
+
+## Find the files and run tests
+
+Run **AugScript: Enable File Icons** for the August icon theme. Source files have a blue mark; `main.aug` has an amber startup mark, and `export.aug` has a purple module mark. **AugScript: Open Welcome** opens the bundled illustrated guide.
+
+Same-file cases appear in VS Code's Testing view. Use that view to run a case or group, or run `aug test` in the terminal. [Tests](testing.md) explains fixtures and endpoint tests. [CLI and configuration](tooling.md) describes language-server integration, native cache settings, and command-line tools.