@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/docs/compatibility.md

@@ -1,6 +1,6 @@
 # Compatibility and supported platforms
 
-August 0.20 is a preview. This page states the proposed 1.0 compatibility contract and the evidence still needed before it takes effect. The [roadmap](roadmap.md) tracks that release gate.
+August is a preview. This page states the proposed 1.0 compatibility contract and the evidence still needed before it takes effect. The pending 0.21.0 release adds the qualified LLVM/native package profile; the [roadmap](roadmap.md) tracks its release gate.
 
 The [ownership and task conformance page](language-conformance.md) records executable candidate behavior for moves, aliasing, cleanup, cancellation, and delayed errors.
 
@@ -12,7 +12,7 @@ The [ownership and task conformance page](language-conformance.md) records execu
 | CLI and project files | Documented `aug` commands, `main.yaml` keys, `aug-package.json`, and `aug.lock.json` retain compatible reading within 1.x. New fields have defaults; removing or changing a field requires a major release. |
 | First-party packages | CLI, standard, web, and crypto packages use one exact version. A release tests installed tarballs together; mixing versions is unsupported. Explicit user manifests currently require the exact compiler version and retain their own public `export.aug` surface. |
 | Generated specifications | `aug spec` remains deterministic for a given compiler and project. Text and layout can improve between versions; tools should link to source and declarations rather than parse Markdown prose. |
-| Native boundary | `extern C` uses documented C-width mappings and the target platform's C ABI. The generated C runtime and `AugValue` layout are compiler-private today. Before 1.0, the project must either publish and test a versioned adapter ABI or keep that runtime surface private and verify that public `extern C` adapters need no private structure. |
+| Native boundary | `aug-native-abi-1` uses fixed-width scalars, copied buffers and opaque resources over the target C ABI. Package descriptors preserve ownership, release, errors and platform requirements. The runtime's `AugValue` layout and pointer-call services remain compiler-private. The preview ABI must pass its release gates before a 1.x stability promise. |
 
 A change that makes valid 1.x source fail to compile, changes its observable behavior, or removes a documented public name is breaking. A safety or correctness repair may require a narrow exception, but its release must explain the affected code, provide a diagnostic, and provide `aug migrate` support when mechanical migration is possible. Security fixes can be released promptly; they still get a compatibility note.
 
@@ -32,11 +32,11 @@ Rebuild native executables and private dependencies for the target platform afte
 
 | Target | Preview evidence | 1.0 support decision |
 | --- | --- | --- |
-| macOS ARM64 | Local pinned native bootstrap and full suite pass. | Candidate; require repeated CI and packaged CLI tests. |
-| Linux ARM64 | Local Docker full native suite passes; core, crypto, and typed HTTP programs run in the matching runtime image. | Candidate; require repeated CI and package tests. |
-| Linux x86-64 | Docker CI is configured for the same full native suite and runtime smoke programs. | Candidate only after that CI gate passes. |
+| macOS 14+ ARM64 | Installed CLI and real public native libraries pass on macOS 14 with Xcode and Command Line Tools removed. | Candidate; every release must repeat language, debugger, sanitizer, performance and consumer gates. |
+| GNU/Linux ARM64, glibc 2.36+ | Debian 12 CI runs LLVM language/runtime regressions and public imports in a consumer image without compilers, Git or headers. | Candidate; qualify each compiler candidate and deployment bundle. Physical DGX testing remains pending. |
+| GNU/Linux x86-64, glibc 2.36+ | The same Debian 12 CI and clean-consumer profile passes on native x86-64 runners. | Candidate; qualify each compiler candidate and deployment bundle. |
 | Windows and other targets | No full native verification. | Outside the proposed 1.0 support matrix. |
 
-Node.js 24+, a C11 compiler, and the [native prerequisites](tooling.md) are required for source builds. The Docker recipes provide those build tools on Linux. The current runtime schedules tasks on one OS thread. HTTP and OIDC library conformance is tracked separately in the [web and crypto gap ledger](web-library-gaps.md); those application concerns are not language 1.0 gates.
+The pending 0.21.0 consumer workflow requires Node.js 24+ and a supported host. August downloads its pinned compiler/runtime and package artifacts; consumers do not install Clang, LLVM or an SDK. Explicit C reference builds and binding authoring require their [maintainer tools](tooling.md). Musl, Windows and cross compilation are outside this profile. The current runtime schedules tasks on one OS thread. HTTP and OIDC library conformance is tracked separately in the [web and crypto gap ledger](web-library-gaps.md); those application concerns are not language 1.0 gates.
 
 The 1.0 support matrix becomes a commitment only after each candidate target has green CI, installed-package and native integration tests, dependency/license review, and a documented update path. See [production readiness](production-readiness.md) for present limits.

package/docs/contributing-benchmarks.md

@@ -4,24 +4,29 @@ This contributor workflow updates the recorded measurements and charts. Work in
 
 ```sh
 npm ci
+export MACOSX_DEPLOYMENT_TARGET=14.0
 node scripts/bootstrap-native.mjs
-npm run bench:compare
+node scripts/prepare-llvm-tools.mjs
+node scripts/build-runtime-pack.mjs
+AUG_LLVM_HOME="$PWD/.aug-build/llvm-tools" npm run bench:compare -- --http-rounds 5
 ```
 
-Set `AUG_BENCH_PYTHON=/path/to/python3` or `CC=/path/to/clang` to select the reference interpreter/compiler. `AUG_NATIVE_HOME` selects the native dependency cache. The raw result file records versions and a source fingerprint. Compilation timings are included separately from executable run time.
+The suite defaults to LLVM. `--backend c` selects the migration reference, and `--backend llvm --compare-c-backend` measures both backends on the same August programs. Set `AUG_BENCH_PYTHON=/path/to/python3` or `CC=/path/to/clang` to select the reference interpreter/compiler. `AUG_NATIVE_HOME` selects the native dependency cache. The raw result file records versions, LLVM tool/runtime identities and a source fingerprint. Compilation timings are included separately from executable run time. On macOS, prepare native dependencies for the advertised macOS 14 deployment floor before building the runtime pack.
 
-For core/JSON only, extract the smaller native source dependencies and omit HTTP:
+Batch and HTTP clients each run in fresh processes. Their heaps do not retain compiler allocations or earlier workloads. Batch order rotates each round; every executable result is checked. Each HTTP round starts a fresh server, warms its client with 1,000 requests, then validates every measured response. CI records 60 batch samples and five HTTP rounds; the frozen migration thresholds remain unchanged. Failed qualification retains its raw report.
+
+For a smaller core/JSON-only C reference run, extract its source dependencies and omit HTTP. This does not require an LLVM runtime pack:
 
 ```sh
 node scripts/bootstrap-native.mjs --extract-only --only minicoro,yyjson
-npm run bench:compare -- --skip-http
+npm run bench:compare -- --backend c --skip-http
 ```
 
 The full suite writes `docs/benchmark-results.json`; a core-only run writes `.aug-build/benchmarks/results-core.json` and preserves the complete wiki measurements. Focus on selected workloads while trying your own changes:
 
 ```sh
-npm run bench:compare -- --only cpu,collections-200k
-npm run bench:compare -- --only http --http-requests 10000
+AUG_LLVM_HOME="$PWD/.aug-build/llvm-tools" npm run bench:compare -- --only cpu,collections-200k
+AUG_LLVM_HOME="$PWD/.aug-build/llvm-tools" npm run bench:compare -- --only http --http-requests 10000
 ```
 
 Focused runs write `.aug-build/benchmarks/results-focused.json`. Use `--output PATH` to keep separate reports. Render graphs, tables and the exact source examples from the full result file using Python 3.12+:
@@ -36,3 +41,28 @@ npm run docs:build
 
 The plot environment is isolated and ignored; published documentation includes the rendered graphs and needs no Python installation. Review this page's environment, interpretations and limitations when replacing measurements. Short exploratory runs can use `--iterations 3 --warmup 1 --http-rounds 1 --http-requests 1000`; they have less statistical coverage.
 
+## Run the extended C comparisons
+
+The eight additional projects cover floating arithmetic, labeled calls, list traversal, strings, ordered map deletion, checked failures, record allocation and task scheduling. Their August sources live beside adjacent specs in `benchmarks`; independently written C references are in `benchmarks/kernels.c`, and expected results are in `benchmarks/kernels.mjs`.
+
+```sh
+AUG_LLVM_HOME="$PWD/.aug-build/llvm-tools" npm run bench:kernels -- --iterations 30 --output docs/kernel-results.json
+npm run qualification:render
+```
+
+Use `--only float,calls` to focus on selected programs, or `--output PATH` to retain another report. Each program is compiled through LLVM and the C migration backend, then measured against the standalone C reference. Every sample must match the oracle. Reports retain raw timings, build time and executable size. C task calls are sequential and the ordered C map uses linear search; do not describe those as equivalent schedulers or identical table implementations.
+
+## Run the safety gyms
+
+Prepare the maintainer pack as above, then run the full qualification:
+
+```sh
+AUG_LLVM_HOME="$PWD/.aug-build/llvm-tools" AUG_SANITIZER_CC="$PWD/.aug-build/llvm-maintainer/bin/clang" npm run test:gyms:full -- --seed 877966 --vectors 256 --output docs/gym-results.json
+npm run qualification:render
+```
+
+`npm run test:gyms` runs generated cases, rejected contracts and behavioral mutants. The full profile adds source-mutation, ownership/concurrency, native/package, HTTP and sanitizer circuits. Seeds are unsigned 32-bit integers; vector counts must be 1 through 4,096. Empty or invalid domains fail. A full report includes circuit totals and skips instead of silently treating a skipped test as executed.
+
+The ignored replay folder contains each complete original and faulty project with its expected output. Use the CLI version matching the report to replay a selected project with `aug run PATH --backend llvm`. The LLVM candidate's public compiler release remains pending. Reports embed the same source units, so a CI artifact remains reviewable after its temporary folder disappears. Preserve the seed, generator version, compiler source fingerprint and failure report when adding a regression. Do not change the oracle to agree with an incorrect implementation.
+
+After both complete reports pass, render the wiki table and vector chart, inspect the programs and limits, and run `npm run docs:check` and `npm run docs:build`. The renderer's `--check` mode rejects stale published evidence. Do not replace a failed report with a partial or smaller passing run.

package/docs/dev-containers.md

@@ -1,6 +1,6 @@
 # Develop in a VS Code Dev Container
 
-Run the August compiler, tests, and native dependencies inside a Linux container while editing your local project in VS Code. This keeps the C toolchain off your host. The project folder stays on your machine; the compiler and prepared dependencies live in the container image.
+Run the August compiler and tests inside a Linux container while editing your local project in VS Code. The project folder stays on your machine; the CLI downloads its verified compiler/runtime pack into the container's cache. No native toolchain is required on the host or in this development image. These instructions target the pending 0.21.0 release.
 
 You need Docker with a running Linux engine, VS Code, and Microsoft's [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers). Creating a new project also needs Node.js 24 and npm on the host. You can instead open an existing project or a [downloaded example](examples/index.md).
 
@@ -17,20 +17,16 @@ cd hello-august
 mkdir .devcontainer
 ```
 
-Save `.devcontainer/Dockerfile` with these contents. It installs the published CLI and prepares all native libraries, including web and crypto. No host C compiler is required.
+Save `.devcontainer/Dockerfile` with these contents. It installs the CLI; the first run obtains the matching compiler/runtime pack and package artifacts.
 
 ```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
 USER node
 CMD ["sleep", "infinity"]
@@ -55,20 +51,17 @@ Save `.devcontainer/devcontainer.json` beside it:
   },
   "customizations": {
     "vscode": {
-      "extensions": ["augscript.augscript"],
-      "settings": {
-        "augscript.nativeHome": "/opt/augscript/.aug-native"
-      }
+      "extensions": ["augscript.augscript@prerelease"]
     }
   }
 }
 ```
 
-The editor installs the August extension inside the container and points it at the prepared native cache. Terminal commands run as the image's `node` user. On Linux, the Dev Container tooling adjusts that user's ID to match your local files. The [non-root user guide](https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user) explains this behavior.
+The editor installs the August preview extension inside the container. Its bundled compiler and terminal CLI use the same artifact cache. Terminal commands run as the image's `node` user. On Linux, the Dev Container tooling adjusts that user's ID to match your local files. The [non-root user guide](https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user) explains this behavior.
 
 ## Open and run it
 
-Open `hello-august` in VS Code. From the Command Palette, choose **Dev Containers: Reopen in Container**. The first build downloads and compiles the native libraries and can take several minutes. Later opens reuse the built image. When the container is ready, the configured creation command checks your project.
+Open `hello-august` in VS Code. From the Command Palette, choose **Dev Containers: Reopen in Container**. The first image build installs the CLI; the first `aug run` downloads its compiler pack. Later opens and runs reuse these inputs. When the container is ready, the configured creation command checks your project.
 
 Open a terminal **in that VS Code window** and run:
 

package/docs/dgx-consumers.json

@@ -0,0 +1,122 @@
+{
+  "format": 1,
+  "compiler": "0.21.0",
+  "host": "linux-arm64",
+  "ordinaryStarter": {
+    "backend": "llvm",
+    "developmentToolchain": false,
+    "sameFileTests": 1,
+    "frozenOffline": true,
+    "generatedC": false
+  },
+  "installation": "npm-archive-in-node_modules",
+  "nativeToolsOnPath": false,
+  "sourceCache": "fresh",
+  "artifactCache": "fresh",
+  "libraryTransport": "public-release-assets",
+  "compilerTransport": "local-release-asset",
+  "osRelease": "6.17.0-1021-nvidia",
+  "glibcVersion": "2.36",
+  "discardedDeploymentCopies": true,
+  "minimumOSQualification": false,
+  "minimumLibcQualification": true,
+  "realResourceCounters": {
+    "failedConstructor": true,
+    "earlyReturn": true,
+    "cancelledBeforeEntry": true,
+    "liveBuffers": 0
+  },
+  "nativeTasks": true,
+  "standardRuntime": {
+    "json": true,
+    "clock": true,
+    "crypto": true,
+    "httpForms": true,
+    "relocation": true
+  },
+  "directory": "/work/.aug-build/native-consumers-asTCa4",
+  "outcomes": [
+    {
+      "package": "pytorch",
+      "repository": "https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4",
+      "commit": "345c975b74a892ba1e0534503917e937dace6b87",
+      "artifactSha256": "8eb7c5e30635949228548208bda1ac0a7c42801d2299a90ea4d4c2064e700573",
+      "stdout": "5\n7\n9\n21\n",
+      "urlImport": true,
+      "namedAlias": true,
+      "frozenOffline": true,
+      "relocatedBundle": true,
+      "repeatedSpec": true,
+      "backend": "llvm"
+    },
+    {
+      "package": "sqlite",
+      "repository": "https://github.com/GreenPandaStudios/aug-sqlite#v0.1.3",
+      "commit": "54371656e3f8d47d020b974f97267a9017b5e552",
+      "artifactSha256": "480c6dfb5a257fc7047a28dd2eb6f2e60bbcb90ae4e301083a180744dadea8f2",
+      "stdout": "August\n",
+      "urlImport": true,
+      "namedAlias": true,
+      "frozenOffline": true,
+      "relocatedBundle": true,
+      "repeatedSpec": true,
+      "backend": "llvm"
+    },
+    {
+      "package": "zlib",
+      "repository": "https://github.com/GreenPandaStudios/aug-zlib#v0.1.3",
+      "commit": "827a8dde5d0d013d00fff6a2a19036b299d0085f",
+      "artifactSha256": "6da832fa341a1fba96643244da2bb63957107d2b1413743c363fca002e500c66",
+      "stdout": "The world runs on language\n",
+      "urlImport": true,
+      "namedAlias": true,
+      "frozenOffline": true,
+      "relocatedBundle": true,
+      "repeatedSpec": true,
+      "backend": "llvm"
+    },
+    {
+      "package": "blake3",
+      "repository": "https://github.com/GreenPandaStudios/aug-blake3#v0.1.3",
+      "commit": "e4ef39bdc89892e7b0644f5fa03ca4dc8b8042ae",
+      "artifactSha256": "69e4de7c1928254c2fb285b0ecd557c4dd1346e9207d0b7ef56e00957caae748",
+      "stdout": "6437b3ac38465133ffb63b75273a8db548c558465d79db03fd359c6cd5bd9d85\n",
+      "urlImport": true,
+      "namedAlias": true,
+      "frozenOffline": true,
+      "relocatedBundle": true,
+      "repeatedSpec": true,
+      "backend": "llvm"
+    }
+  ],
+  "gallery": [
+    {
+      "package": "pytorch",
+      "run": true,
+      "test": true,
+      "spec": true,
+      "backend": "llvm"
+    },
+    {
+      "package": "sqlite",
+      "run": true,
+      "test": true,
+      "spec": true,
+      "backend": "llvm"
+    },
+    {
+      "package": "zlib",
+      "run": true,
+      "test": true,
+      "spec": true,
+      "backend": "llvm"
+    },
+    {
+      "package": "blake3",
+      "run": true,
+      "test": true,
+      "spec": true,
+      "backend": "llvm"
+    }
+  ]
+}