@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/reference.md

@@ -1,6 +1,8 @@
-# AugScript language guide
+# Language reference
 
-Version 0.18. The language aims for code that communicates behavior, dependencies, and effects to a developer seeing a module for the first time.
+Use this page to look up the implemented language rules. It covers syntax, types, visibility, effects, dependency injection, ownership, and checked failures. For a first introduction, read [the August book](learn/index.md). For the reasons behind the design, read [why August exists](about.md).
+
+The reference is maintained with the compiler in this repository. August is experimental; [compatibility](compatibility.md) describes its version policy. Examples marked with a project and filename form complete applications and are checked by the documentation tests. Short `text` blocks illustrate syntax and are not standalone projects.
 
 ## A complete project
 
@@ -30,7 +32,7 @@ Application(resolve Console console) implements Runnable:
         console.write(value="Hello, AugScript!")
 ```
 
-Run `node bin/aug.mjs run PROJECT`, or choose **AugScript: Run Project** in VS Code. Node.js 24+ and a C11 compiler are required.
+Run `npx @greenpandastudios/aug-cli@next run PROJECT`, or choose **AugScript: Run Project** in VS Code. Node.js 24+ and a C11 compiler are required; prepare [native dependencies](packages.md#npm-registry) before execution.
 
 ## Blocks and statement boundaries
 
@@ -114,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
@@ -182,9 +197,9 @@ Empty literals require context: `List<int> values = []`, `Set<int> values = {}`,
 
 | Type | Reading | Mutation |
 | --- | --- | --- |
-| List | `length()`, `get(index=...)` unless IndexError, `at(index=...)` returns T? | `append(value=...)` |
+| List | `length()`, `get(index=...)` unless IndexError, `at(index=...)` returns `optional T` | `append(value=...)` |
 | Set | `length()`, `contains(value=...)` | `add(value=...)` |
-| Map | `length()`, `contains(key=...)`, `get(key=...)` returns V? | `set(key=..., value=...)` |
+| Map | `length()`, `contains(key=...)`, `get(key=...)` returns `optional V` | `set(key=..., value=...)` |
 | Tuple | `length()`, `get(index=constant)` with compile-time bounds | None |
 
 Managed mutations need a borrow; owned collections mutate directly. Collections cannot store borrowed or owned references by copying them. Reference results grant reading.
@@ -193,9 +208,9 @@ Tuple destructuring introduces new local names and checks arity. `for item in va
 
 ## Functions, effects, and capabilities
 
-A bare header without `implements` declares a function. Omitting `returns` means void. Non-void bodies must return or throw on every path. A bodyless top-level declaration cannot be called unless it is an extern declaration.
+A bare header without `implements` declares a function. A body infers its result from return expressions or an implemented interface. A body with no returned value has a void result; a bodyless signature needs `returns T` for a non-void result. Non-void bodies must return or throw on every path. A bodyless top-level declaration cannot be called unless it is an extern declaration.
 
-Public standalone functions and interface contracts are pure unless they declare capabilities. State transitions declare `changes self` or `changes input`; mutable reference inputs require `borrow` or `own`. A helper cannot mutate a managed input, an alias, or nested objects reachable through it.
+Bodies infer capability use and state transitions. Bodyless interfaces declare permitted `uses` and `changes`; mutable reference inputs require `borrow` or `own`. A helper cannot mutate a managed input, an alias, or nested objects reachable through it.
 
 I/O uses capability interfaces and checked `uses dependency.operation` contracts. Capability types have interface behavior and permit explicit adapter substitution. The standard `august.io` folder provides Console/SystemConsole, FileReader/FileWriter/LocalFiles, and Arguments/ProcessArguments.
 
@@ -210,7 +225,7 @@ announce(message="Dependencies are visible")
 ```aug project=capabilities-guide file=messages.aug
 import Console from august.io
 
-announce(resolve Console console, string message) uses console.write:
+announce(resolve Console console, string message):
     console.write(value=message)
 ```
 
@@ -218,25 +233,29 @@ A caller's contract must include the effects of its calls and interceptor layers
 
 ### Short implementation headers
 
-Class methods and private `_helpers` infer `uses` when it is omitted. Interfaces, public standalone functions, interface default methods, and interceptor `around` methods retain explicit effect contracts. An explicit `uses` clause is an upper bound, including on implementations. `changes` and `unless` are still explicit.
+Executable functions, methods, interface defaults, and interceptors infer omitted `returns`, `changes`, `uses`, and `unless` clauses. You write the work once. Return expressions determine the result; calls and writes determine capabilities and observable mutations; failures that escape catches determine checked errors. Record validation also infers escaping failures.
 
 ```text
-import Console from august.io
+import Console and FileReader from august.io
 
 interface Logger:
     log(string message) uses Console.write
 
 ConsoleLogger(resolve Console console) implements Logger:
     log(string message):
-        _write(console, message)
+        console.write(value=message)
 
-_write(Console console, string message):
-    console.write(value=message)
+load(resolve FileReader files, string path):
+    return files.read(path)
 ```
 
-Both bodies infer `Console.write`; the interface states it once. Inference follows calls, generic substitutions and interceptor layers to a fixed point, so declaration order does not matter. Hover and `aug explain` show inferred capabilities; generated library API pages include them. Calling an inferred helper from a pure public function is a compile error. A pure interface cannot acquire hidden I/O through its implementation.
+The editor shows `uses Console.write` beside `log` and `returns string uses FileReader.read unless FileError` beside `load` as non-editable hints. These clauses are absent from saved code. Hover, `aug explain`, generated API docs, and `aug spec` use the same checked contracts. Formatting keeps concise source; it preserves annotations you wrote deliberately.
 
-Capability implementations inherit their operation contract even when a test adapter does no I/O. This includes shared-state capabilities such as `ExpiringStore<T>`. Constructors and `drop()` remain pure; inference does not permit I/O while holding a lock. Type-changing recursive generic effect inference that cannot converge requires an explicit finite `uses` clause.
+Bodyless interfaces and foreign declarations describe contracts the compiler cannot inspect. A written clause remains a checked assertion: `returns void` rejects a returned value, and an explicit `uses` or `unless` limits the body. Implementations must satisfy their interface. An interface with no effects remains pure. Inference follows calls and generic substitutions independently of declaration order. Recursive results without an anchor, empty collections without a contextual type, and expanding generic contracts need an explicit type or finite contract.
+
+`borrow`, `own`, `resolve`, `mutable`, HTTP input sources and error-status mappings express permissions or choices. They stay in source. Inferred mutation cannot grant access to a managed input. Constructors and `drop()` keep their purity rules, and inferred I/O remains forbidden under a lock. A fresh local `Shared` value needs no artificial external-effect clause; retained external shared state still requires its capability or mutation contract. A forwarding interceptor can inherit each target's result; an interceptor that needs a fixed result contract can state it.
+
+Capability implementations inherit their operation contract even when a test adapter does no I/O. This includes shared-state capabilities such as `ExpiringStore<T>`. An unhandled error in main still fails checking; inferred propagation through a helper does not handle that failure.
 
 Outside main and test setup, every injected dependency is declared in the callable/class header. Calls forward the one compatible header dependency; multiple candidates require a clearer header. Constructor and interceptor dependencies are checked the same way. Body-level `resolve` is rejected with a fix to lift it into the header.
 
@@ -286,10 +305,21 @@ Nullable locals narrow after null checks, short-circuit conditions, match patter
 
 `match value` uses `when null`, `when some name`, `when true`, `when false`, or `when Type name`. Nullable and bool matches must cover every case. Open class/interface domains require `else`. Duplicate/unreachable cases and incompatible patterns are errors.
 
-An error satisfies Error. A callable declares specific errors with `returns T unless FileError and DomainError`. It can throw any value satisfying its declaration; declaring Error accepts any Error implementation. Calls must catch or propagate all effective errors, including interceptor layers.
+An error satisfies Error. A body infers escaping errors. A bodyless signature or explicit bound names specific errors with `returns T unless FileError and DomainError`. It can throw any value satisfying its declaration; declaring Error accepts any Error implementation. Calls must catch or propagate all effective errors, including interceptor layers; executable callers infer propagation when unless is omitted.
 
 `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
@@ -312,7 +342,7 @@ import FileReader from august.io
  * @return UTF-8 text.
  * @throws FileError Reading failed or the text is invalid.
  */
-load(resolve FileReader files, string path) returns string uses files.read unless FileError:
+load(resolve FileReader files, string path):
     return files.read(path=path)
 ```
 

package/docs/releasing.md

@@ -5,37 +5,66 @@ All first-party packages and the extension use one compiler-compatible version.
 ## Verify and create artifacts
 
 ```sh
-node scripts/version.mjs 0.19.0
+node scripts/version.mjs 0.21.0
 npm ci
 npm --prefix vscode ci
 node scripts/bootstrap-native.mjs
+node scripts/prepare-llvm-tools.mjs
+node scripts/prepare-llvm-maintainer.mjs
+node scripts/build-runtime-pack.mjs
+export AUG_LLVM_HOME="$PWD/.aug-build/llvm-tools"
 npm run version:check
 npm run check
 npm test
 npm run docs:check
 npm run docs:build
+node scripts/merge-compiler-packs.mjs .aug-build/release-packs
 npm run package:packages
 npm run test:packages -- --native
 npm run package:extension
 node scripts/release-artifacts.mjs
+node scripts/publish-release.mjs dist/release --verify-only
+node scripts/publish-extension.mjs dist/release --verify-only
 ```
 
-Update both changelogs and relevant guides, and commit regenerated docs. The final artifact step combines four installable npm tarballs, a VSIX, offline documentation, package metadata and SHA-256 checksums under `dist/release`. It excludes native caches, private credentials and application build output.
+The merge step requires the exact qualified producer archives and manifests for all three hosts under `.aug-build/release-packs`; `release.yml` obtains them before packaging. Update both changelogs and relevant guides, and commit regenerated docs. The final artifact step combines four installable npm tarballs, a VSIX, compiler packs, offline documentation, package metadata and SHA-256 checksums under `dist/release`. It excludes native caches, private credentials and application build output.
 
 ## GitHub release
 
 After verification and committing, create and push the version tag:
 
 ```sh
-git tag v0.19.0
-git push origin main v0.19.0
+git tag v0.21.0
+git push origin main v0.21.0
 ```
 
-`release.yml` validates the tag against every manifest, runs compiler/native/docs/package gates, and uploads artifacts to a **draft prerelease**. Review the draft and publish it in GitHub Releases. `ci.yml` checks pushes and pull requests. Linux CI builds the pinned full native stack, runs the native suite, and executes core and crypto apps in the matching runtime image. macOS CI runs the same native suite with its private bootstrap.
+`release.yml` validates the tag against every manifest, runs compiler/native/docs/package gates, and uploads artifacts to a **draft prerelease**. Review the draft and publish it in GitHub Releases. Publishing starts **Publish npm packages** and **Publish VS Code extension** automatically. Each workflow deploys the archives attached to that release. Changing an asset after review invalidates its checksum.
+
+`ci.yml` checks pushes and pull requests. Linux CI builds the pinned full native stack, runs the native suite, and executes core and crypto apps in the matching runtime image. macOS CI runs the same native suite with its private bootstrap.
+
+The automatic publishers are included starting with `v0.20.1`. Existing tags keep their original workflows; the `v0.20.0` draft does not contain these scripts.
+
+The manually published Marketplace `0.19.0` contains files that differ from the VSIX attached to the `v0.19.0` GitHub release. It is not a matching deployment of that archive. Use a new version for the first automated extension release; do not bypass the content comparison to skip an older mismatch.
 
 ## npm publication
 
-The intended scope is `@greenpandastudios`. Claim this npm identity or choose an owned scope consistently before the first registry release. Create the initial packages with the owner's authenticated npm account. GitHub tarballs work independently of registry setup.
+The LLVM preview release builds official pinned LLVM tools and the August runtime
+on macOS ARM64, Linux x86-64 and Linux ARM64 before packaging. Linux producers
+use the pinned Debian 12 maintainer image. `scripts/merge-compiler-packs.mjs`
+rejects missing, duplicate, stale or modified platform inputs, then records all
+exact compiler archive hashes in the CLI and bundled editor compiler. The GitHub
+release includes every selected archive.
+Runtime compilation remains a maintainer operation. Application installation
+downloads the reviewed pack and does not build LLVM or invoke Clang. CI runs the
+LLVM execution tests with its prepared toolchain; unsupported platforms retain
+explicit preview diagnostics. See [native packages](native-packages.md).
+Producer jobs require source breakpoint/variable inspection, actual LLVM ASan
+instrumentation with a failing negative control, runtime UBSan, and the frozen
+paired C/LLVM performance limits. Consumer jobs exercise an ordinary default
+LLVM starter and all four public native repositories without native tools,
+including frozen/offline locks, cleanup and relocated deployment bundles.
+
+The packages use the `@greenpandastudios` npm scope. Verify ownership and each package's trusted publisher before a release. GitHub tarballs can also be installed directly.
 
 Configure a trusted publisher for each of the four npm packages:
 
@@ -47,19 +76,19 @@ Configure a trusted publisher for each of the four npm packages:
 
 Use npm CLI 11.5.1+ and GitHub-hosted runners. The workflow grants `id-token: write` for OIDC and needs no stored npm publishing token. Match package repository URLs to this repository. See [npm's trusted publisher instructions](https://docs.npmjs.com/trusted-publishers/).
 
-Publishing a reviewed GitHub release automatically runs **Publish npm packages**. To retry, dispatch that workflow with the existing verified version tag. It checks out that tag, checks types/docs/installed artifacts, then publishes standard library, web, crypto and CLI in dependency order with public access and the `next` dist tag. The `npm` environment can hold owner-configured release protection. Existing versions cannot be overwritten; inspect partial runs before retrying.
+The job downloads the four reviewed tarballs, `packages.json` and `SHA256SUMS`. It checks every archive's SHA-256 and SHA-512 integrity, exact version and complete manifest against the tagged source before publishing anything. It checks all existing registry versions, then publishes standard library, web, crypto and CLI in that order with public access and the `next` dist tag. Lifecycle scripts are disabled. No rebuild or dependency installation runs in the npm deployment job.
 
-## VS Code Marketplace
+Retries skip a version only when its registry integrity matches the release archive. A registry failure or a different published archive stops deployment. Each new publication is checked against the registry before proceeding. npm may accept an upload several minutes before its public metadata becomes available. The publisher on main checks visibility at five-second intervals for about five minutes per package; it retries only missing-version responses and uploads each archive once. If that wait expires, let npm finish processing before retrying the same release. The `v0.20.1` publisher checks visibility immediately and may need a retry after each accepted upload; the bounded wait applies to future tags.
+
+The CLI is published last because its dependencies use exact matching versions. An interrupted run can leave some libraries published; retry the same release to finish. Retries leave already-published versions and their dist tags alone. This pipeline publishes preview packages to `next`; promoting a release to `latest` remains a separate maintainer decision.
 
-Confirm ownership of the `augscript` Marketplace publisher. Publishing a reviewed GitHub release runs **Publish VS Code extension** (`publish-marketplace.yml`); manual dispatch accepts the same published tag for retries. It downloads the release's VSIX, verifies its SHA-256 checksum, version and `augscript.augscript` identity, then publishes that exact artifact. VSIX files remain available directly from GitHub Releases.
+## VS Code Marketplace
 
-One-time owner setup follows [Microsoft's secure publishing guide](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#secure-automated-publishing-to-visual-studio-marketplace):
+The extension identity is `augscript.augscript`. An owner of the `augscript` publisher must configure a Marketplace trusted publishing policy for `GreenPandaStudios/augscript`, workflow `publish-extension.yml` and the `marketplace` deployment environment. VSCE 4.0.0 supports `vsce publish --oidc` on GitHub Actions; the workflow requests a short-lived credential and does not use a stored PAT or an Azure subscription. See [the shipping VSCE trusted publishing instructions](https://github.com/microsoft/vscode-vsce/blob/v4.0.0/README.md#trusted-publishing). Account-side trust must be configured before the first deployment; adding a workflow does not grant publisher access.
 
-- Create a Microsoft Entra identity and grant it publishing access to the `augscript` Marketplace publisher.
-- Add a GitHub federated credential with issuer `https://token.actions.githubusercontent.com`, audience `api://AzureADTokenExchange`, and subject `repo:GreenPandaStudios/augscript:environment:marketplace`.
-- Create the GitHub environment `marketplace` and set its variables `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` to that identity's IDs. Configure release protection there if needed.
+The preparation job downloads the reviewed VSIX, verifies its checksum, complete manifest, logo and bundled compiler, and installs the locked publishing tool with lifecycle scripts disabled. It passes these files to a separate `marketplace` job with OIDC permission. That job rechecks the VSIX and publishes it with `--packagePath`, so publication does not build another extension or run `vscode:prepublish`.
 
-The workflow uses Azure login through OIDC and the pinned `vsce` CLI's `--azure-credential` support. No publishing token is stored. The first public listing requires the publisher identity setup; the repository does not establish ownership of a Marketplace namespace. The intended listing is [AugScript](https://marketplace.visualstudio.com/items?itemName=augscript.augscript), currently unpublished.
+For retries, the publisher downloads an existing Marketplace version and compares all files under `extension/` with the reviewed VSIX. Marketplace signature metadata outside that directory may differ. A changed, missing or additional extension file stops the retry. After uploading, the job downloads and verifies the published version, allowing roughly a minute for indexing. If confirmation still fails after an upload, wait for the version to become available and retry. VSIX files remain available from GitHub for direct installation.
 
 The packaging script supplies the repository's `vscode` directory as the HTTPS
 base for README images. Verify those URLs are public before Marketplace
@@ -68,7 +97,15 @@ users. The extension logo and **AugScript: Open Welcome** images are bundled
 locally and do not depend on that image host. To update artwork, run
 `npm --prefix vscode run artwork` and commit the rendered PNGs.
 
-Global Azure DevOps PATs retire on December 1, 2026; this project does not introduce a new long-lived Marketplace PAT. Marketplace identity setup is an external owner prerequisite.
+## Deployment protection and retries
+
+Configure GitHub environments named `npm` and `marketplace`. Allow only tags matching `v*`; use required reviewers if your release process needs another approval. Keep the npm environment name identical to each package's trusted publisher configuration, and the Marketplace policy aligned with its workflow and environment. See [GitHub's environment protection guide](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment). Restrict who can create or move release tags through repository rules.
+
+Both workflows also accept a manual retry. Open the appropriate workflow in Actions, select the release tag as the workflow ref, and enter the same tag in the `tag` input. A branch ref, mismatched version, draft release or tag moved since the run began is rejected before publication. The tag must contain these publishing workflows and scripts. Re-running the failed job on its original run also retains the exact tagged source. npm and Marketplace have separate concurrency groups and deployment environments, so a failure at one destination can be retried independently.
+
+Release creation uses the repository's `GITHUB_TOKEN` to create a draft. A maintainer must publish that draft through GitHub Releases or their own authorized GitHub CLI session. Events produced only by `GITHUB_TOKEN` do not start another workflow; do not replace this review step with a token-authenticated automatic publish unless you also add an explicit deployment handoff. See [GitHub's workflow trigger rules](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow).
+
+If npm reports an authentication failure, check all four package connections, their exact workflow/environment spelling, permission for direct `npm publish`, and OIDC permission. For a Marketplace failure, check the publisher policy and `marketplace` environment. Do not place credentials in workflow files or release assets. The scripts distinguish missing versions from authorization and service errors; investigate the reported error before retrying.
 
 ## Documentation deployment
 
@@ -76,4 +113,56 @@ Enable GitHub Pages with **GitHub Actions** as its publishing source. `docs.yml`
 
 ## Current limits
 
-August is experimental. Native web/crypto bootstrap supports macOS and Linux; other platforms are unverified. Registry and Marketplace identities require owner configuration. User-authored source packages are supported through npm transport; prebuilt native dependency releases and a stable external native adapter ABI remain future work. See [the gap ledger](web-library-gaps.md) and [performance assessment](performance.md).
+August is experimental. The LLVM/native candidate targets macOS 14+ ARM64 and GNU/Linux x86-64/ARM64 with glibc 2.36+; other platforms are unverified. npm and Marketplace deployment require owner-configured trust. The first `v0.20.1` Marketplace attempt failed during the VSCE 4.0.0 OIDC token exchange with an API-version error. The publisher now pins VSCE 4.0.1-1, whose [upstream fix](https://github.com/microsoft/vscode-vsce/blob/main/src/oidc.ts) supplies the API version and federated authorization scheme. Automated Marketplace publication remains unverified until a real release passes; the checked VSIX is available from GitHub Releases. User libraries use ordinary public Git repositories, local folders, or npm archives. The four native library repositories publish prebuilt artifacts; the 0.21.0 compiler release remains pending. Stabilizing the external adapter ABI is a 1.0 gate. See [the gap ledger](web-library-gaps.md) and [performance assessment](performance.md).
+## Native preview qualification
+
+Before publishing a compiler with native package support, build its LLVM pack
+before the npm archives and extension. `scripts/release-artifacts.mjs` checks
+that both shipped manifests pin that exact compiler archive. The release job
+runs `scripts/qualify-native-consumers.mjs --local-compiler`: it installs the npm
+archives, fetches the four native libraries from their public repositories and
+release URLs, then runs LLVM programs through URL imports and named aliases.
+Git, native compilers, and SDK paths are unavailable to those CLI processes.
+Frozen offline runs must preserve the locks and produce the same results.
+
+The release consumer jobs repeat this check on macOS 14 ARM64 and each Linux
+architecture. The macOS runner removes Xcode and Command Line Tools. Linux uses
+the pinned Node/Debian slim image with no compiler, Git or development headers.
+A draft is created only after all consumer jobs pass. A local result on a
+newer OS does not qualify the minimum OS. After release publication, omit
+`--local-compiler` to verify the compiler download too. Keep the resulting JSON
+report with release evidence; never commit artifact caches or generated binaries.
+
+Before library artifacts are public, contributors can pass
+`--candidate-libraries DIRECTORY --local-compiler` to the qualification script.
+`DIRECTORY` contains the four `aug-*` repository folders and their measured native
+archives. This mode installs the same CLI archives and checks each native file
+through the installed verifier, but reports local transport and does not claim
+repository URL/download acceptance. Public release gates omit this option.
+On a small test VM, `--discard-builds` removes verified deployment copies after
+their checks while keeping the source, locks, compiler outputs and JSON evidence.
+
+Each library candidate records the build commit and a complete input fingerprint:
+August source, the ABI descriptor, headers, native code, dependency locks and
+build recipes. Before adding release artifact pins, run
+`node native/verify-candidate.mjs PATH_TO_CANDIDATE_JSON` in the library repository.
+Run it again after updating the manifest. Only artifact metadata may change;
+changed binding or build inputs require a new candidate. Publish the exact tested
+archives without rebuilding them. `native/library-qualification.json` records
+the reviewed package tag, source commit and archive hash for each consumer host.
+A platform without reviewed pins fails qualification before any library download.
+
+The four library repositories keep a `release-candidates.json` record for the
+reviewed build run and source commit. Their tag workflow uses the shared release
+template under `native/templates` and the canonical assembly/publication scripts
+under `scripts`. It downloads that successful run, checks all three platform
+archives against the tagged manifest and source identity, then verifies the
+uploaded bytes before publishing. Retries accept an existing file only when its
+bytes match; they do not overwrite release assets. Keep the scripts in those
+repositories aligned when this maintainer protocol changes.
+
+To retry a library release after a publishing-tool correction, run its workflow
+on main and enter the existing version tag. The job checks out that immutable tag
+for source and manifest verification and uses the current maintainer publisher.
+It validates the tagged commit again before creating or changing a release.
+Partial uploads remain draft until the complete archive set passes byte checks.

package/docs/research/code-to-natural-language.md

@@ -0,0 +1,108 @@
+# Research: deterministic prose from source code
+
+Research date: 2026-09-29. This note supports August's compiled specifications: connected prose describing local implementation behavior, with references to the dependency surfaces that the implementation actually uses. It records research evidence and proposed engineering choices; it is not an implementation status report.
+
+## Findings that matter for August
+
+A practical approach is to generate text from explicit program facts through document planning, sentence planning, and realization. Classic NLG separates content determination, discourse planning, aggregation, lexicalization, reference generation, and realization [1]. McBurney and McMillan apply these ideas to code, including fixed message ordering and rules that combine related phrases [5]. This provides a stronger starting point than emitting an independent template for each syntax node.
+
+Aggregation can reduce repeated subjects and predicates while retaining the facts being communicated. Dalianis and Hovy explicitly distinguish repackaging facts from dropping selected information, and restrict reordering to zones where ordering is free [8]. For program explanations, that restriction matters: execution order, branch scope, mutation, and error behavior cannot be treated as freely reorderable facts.
+
+Program names provide useful linguistic hints. They do not establish a function's semantics. SWUM represents action, theme, and argument relationships in names and signatures [3]. The parameter-comment work combines these clues with control flow and data dependencies and acknowledges limitations from uninformative names and abbreviations [4]. August should establish behavioral claims from its compiler representations before choosing wording.
+
+Context can help explain how a function fits into its program. The context-summary research uses call relationships and output uses [5, 6]. Its relevance ranking deliberately selects a small subset of context, and its evaluations concern summaries. It does not demonstrate generation of a complete executable or behavioral specification.
+
+## Primary literature reviewed
+
+Entries report what each source supports, followed by the limit relevant to this task. Sources are linked to the paper or its publisher/author copy. Full text was inspected where available; the two abstract-only entries are marked explicitly.
+
+### 1. Reiter and Dale, 1997: the generation pipeline
+
+Ehud Reiter and Robert Dale. *Building Applied Natural Language Generation Systems*. Natural Language Engineering 3(1), 57–87, March 1997. [Publisher record and abstract](https://www.cambridge.org/core/journals/natural-language-engineering/article/abs/building-applied-natural-language-generation-systems/FEB374A3FF652F06D8567A6FAB2EF36E), [author-hosted PDF](https://web.science.mq.edu.au/~rdale/publications/papers/1997/jnle97.pdf). DOI: 10.1017/S1351324997001502.
+
+The paper identifies content determination, discourse planning, sentence aggregation, lexicalization, referring expression generation, and linguistic realization as distinct tasks in applied NLG. Its stated emphasis is techniques suitable for practical systems. This gives August a vocabulary for separating semantic extraction from paragraph structure and wording. **Access limit:** the publisher abstract was read; author PDF fetching failed during this review. Detailed pipeline mechanics are additionally supported by the full-text implementation in [5]. The paper is architectural guidance, not a proof of specification completeness or reproducibility.
+
+### 2. Sridhara et al., 2010: method summary comments
+
+Giriprasad Sridhara, Emily Hill, Divya Muppaneni, Lori Pollock, and K. Vijay-Shanker. *Towards Automatically Generating Summary Comments for Java Methods*. ASE 2010, 43–52, September 2010. [Publication DOI](https://doi.org/10.1145/1858996.1859006), [paper abstract](https://www.researchgate.net/publication/220883580_Towards_automatically_generating_summary_comments_for_Java_methods).
+
+The authors describe deriving descriptive method summaries from method signatures and bodies, and report programmer judgments of accuracy, important content, and conciseness. This is directly relevant precedent for source-based comment generation. **Access limit:** only the original paper's abstract was accessible; the publisher rejected access and the linked repository copy was unavailable. Implementation details should not be attributed to an independently read full text here. The later full-text papers [4, 5] discuss its selection of important statements. Neither favorable summary judgments nor selecting important content establishes that every behavior is explained.
+
+### 3. Hill, Pollock, and Vijay-Shanker, 2011: linguistic roles in code
+
+Emily Hill, Lori Pollock, and K. Vijay-Shanker. *Improving Source Code Search with Natural Language Phrasal Representations of Method Signatures*. ASE 2011, November 6–10, 2011. DOI: 10.1109/ASE.2011.6100115. [Author-uploaded full text](https://www.researchgate.net/publication/220883654_Improving_source_code_search_with_natural_language_phrasal_representations_of_method_signatures).
+
+The paper uses SWUM to derive action, theme, secondary argument, and auxiliary argument roles. Its search score incorporates word location, role, distance from a phrase's head, and usage. The evaluation covers eight search tasks from four Java programs. Phrasal structure can distinguish adding an auction from adding an auction link. This supports keeping noun phrases and argument roles intact during wording. Its empirical result concerns search relevance, not generated documentation accuracy; the authors discuss limited generalization beyond Java. August's symbol resolution must establish what is called, independently of lexical heuristics.
+
+### 4. Sridhara, Pollock, and Vijay-Shanker, 2011: parameters in context
+
+Giriprasad Sridhara, Lori Pollock, and K. Vijay-Shanker. *Generating Parameter Comments and Integrating with Method Summaries*. ICPC 2011, 71–80. DOI: 10.1109/ICPC.2011.28. [Full paper](https://www.cs.kent.edu/~jmaletic/cs63902/Papers/Pollock11.pdf).
+
+This method-local approach combines control flow, control and data dependencies, def-use chains, and SWUM information to identify a parameter's main role and connect it to the method's computation. It supports parameter comments and integration into method summaries. Nine experienced developers evaluated the results. The authors explicitly describe reduced readability and analysis accuracy from abbreviations and a dependence on meaningful identifiers. The approach emphasizes primary usage, so it does not justify omitting secondary parameter uses when August promises comprehensive local behavior.
+
+### 5. McBurney and McMillan, 2014: readable method context
+
+Paul W. McBurney and Collin McMillan. *Automatic Documentation Generation via Source Code Summarization of Method Context*. ICPC 2014, 279–290, June 2–3, 2014. [Author-hosted full paper](https://sdf.org/~cmc/papers/mcburney_icpc_2014.pdf).
+
+The technique combines call graphs, PageRank-selected contextual methods, SWUM, and a custom NLG pipeline. Its document plan uses predefined message ordering; aggregation combines related phrases and suppresses repeated subjects and verbs. A study with twelve Java programmers evaluates understanding of internal behavior, purpose, and usage. This is particularly useful evidence that rule-driven code descriptions can form connected sentences. However, it selects only some context and uses simplifying assumptions about names and outputs. Its context descriptions are clues about role, not verified design intent or an exhaustive dependency contract.
+
+### 6. McBurney and McMillan, 2015 accepted manuscript: stronger comparison
+
+Paul W. McBurney and Collin McMillan. *Automatic Source Code Summarization of Context for Java Methods*. IEEE Transactions on Software Engineering, accepted manuscript bearing 2015 copyright and DOI 10.1109/TSE.2015.2465386. [Full accepted manuscript](https://sdf.org/~cmc/papers/mcburney_tse15.pdf).
+
+This extension compares context summaries with expert summaries and an existing automatic summarizer. Its conclusion reports better contextual information than manual summaries, while human summaries were more accurate and concise; combining generated context with existing summaries improved documentation. This qualifies the earlier results: useful context does not imply human-level overall quality. The linked copy is a prepublication manuscript, so 2015 here identifies that manuscript rather than asserting the final issue's publication year. These studies are from the same research line and should not be counted as independent replications.
+
+### 7. Reiter, Mellish, and Levine, 1995: documentation and links
+
+Ehud Reiter, Chris Mellish, and John Levine. *Automatic Generation of Technical Documentation*. Applied Artificial Intelligence 9, 259–287, 1995; preprint submitted November 1994. [Full preprint](https://arxiv.org/pdf/cmp-lg/9411031), [version metadata](https://arxiv.org/abs/cmp-lg/9411031).
+
+The IDAS work generates documentation from domain knowledge and linguistic/contextual models, including hypertext nodes and links. It discusses the expense of adding information absent from existing design databases and checking whether generated language faithfully reflects the knowledge base. This supports retaining explicit facts and structured references as generator input. It also shows why the quality of the underlying model constrains the text. IDAS concerns equipment help and tailored documentation, not compiler extraction from arbitrary programs; it does not solve August's dependency selection problem.
+
+### 8. Dalianis and Hovy, 1993 workshop version: aggregation
+
+Hercules Dalianis and Eduard Hovy. *Aggregation in Natural Language Generation*. EWNLG 1993 workshop version, later a chapter in *Trends in Natural Language Generation*. [Author-hosted manuscript](https://people.dsv.su.se/~hercules/papers/EGEN_Aggregation_NLG_1996.pdf).
+
+The manuscript identifies aggregation operations from a small telephone-domain study, including grouping shared subjects and predicates. It distinguishes reducing redundancy from entirely omitting information chosen for communication. Its ordering discussion confines rearrangement to free-order zones in a discourse structure. Twelve participants completed the questionnaire; nine produced aggregated text. This provides concrete rules for turning repeated factual sentences into paragraphs. Its small constrained domain and assumptions about discourse structure limit generalization. The manuscript's heading identifies the 1993 workshop version; the filename should not be used as publication metadata.
+
+### 9. Dalianis, 1995: aggregation for formal specifications
+
+Hercules Dalianis. *Aggregation in the NL-generator of the Visual and Natural Language Specification Tool*. EACL 1995, 286–290. [Full paper](https://aclanthology.org/E95-1042.pdf).
+
+VINST paraphrases formal information through naturalization, compacting, and surface grammar stages. The paper describes repeated noun phrase removal and proposes predicate grouping and a bidirectional grammar to improve tedious fact-base descriptions. This is an unusually close precedent for readable natural language from a formal specification representation. The discussion concerns a telecom specification prototype and a proposed architecture improvement, not an empirical demonstration that all program behaviors can be paraphrased without ambiguity. Use its representation-oriented approach while verifying August's individual language constructs.
+
+### 10. Gatt and Reiter, 2009: realization under developer control
+
+Albert Gatt and Ehud Reiter. *SimpleNLG: A Realisation Engine for Practical Applications*. ENLG 2009, 90–93, March 30–31, 2009. [Full paper](https://aclanthology.org/W09-0613.pdf).
+
+SimpleNLG separates tactical linguistic choices from mechanical syntax, morphology, and linearization. Developers retain control over how semantic inputs map to phrase structures; the engine supports mixed canned and constructed text. This supports a small controlled realization layer handling coordination, agreement, inflection, and punctuation. It does not choose which source-code facts are true or complete. August need not adopt the Java library: the architectural separation is useful in a TypeScript compiler, and byte-identical output remains an engineering requirement to verify separately.
+
+### 11. Roy, Fakhoury, and Arnaoudova, 2021: evaluation metrics
+
+Devjeet Roy, Sarah Fakhoury, and Venera Arnaoudova. *Reassessing Automatic Evaluation Metrics for Code Summarization Tasks*. ESEC/FSE 2021, 1105–1116, August 23–28, 2021. DOI: 10.1145/3468264.3468588. [Author-hosted full paper](https://veneraarnaoudova.com/wp-content/uploads/2021/09/2021-FSE-CR-Reassessing-Automatic-Evaluation-Metrics-for-Code-Summarization-Tasks.pdf).
+
+A study with 226 human annotators compares automatic metrics and human summary judgments. In its setting, improvements below two metric points do not reliably indicate quality improvements, and corpus BLEU remains unreliable for some larger differences. This argues against treating lexical overlap as the acceptance gate for August's prose. These observations concern the studied datasets and summarizers; they are not universal numerical thresholds. August needs direct semantic coverage checks and reader comprehension judgments, as separate dimensions.
+
+### 12. Nie et al., 2022: evaluation should match use
+
+Pengyu Nie, Jiyang Zhang, Junyi Jessy Li, Ray Mooney, and Milos Gligoric. *Impact of Evaluation Methodologies on Code Summarization*. ACL 2022, 4936–4960, May 2022. DOI: 10.18653/v1/2022.acl-long.339. [Full paper](https://aclanthology.org/2022.acl-long.339.pdf).
+
+The authors compare mixed-project, cross-project, and time-segmented evaluation of learned code summarizers. Different splits can lead to conflicting conclusions, and the paper maps evaluation methods to intended use cases. This is chiefly relevant if August later adds learned lexical or summary components. Its broader lesson motivates representative acceptance examples and revisions of real programs. A deterministic rule generator has no training leakage in the same sense, so the paper's machine-learning results should not be presented as direct evidence of August's quality.
+
+## Proposed engineering choices for August
+
+These are recommendations derived from the requirements and the literature, not findings that the papers prove or claims that the current generator implements them.
+
+1. Extract an immutable behavior representation from resolved compiler structures. Each fact should retain its construct identity, lexical scope, source location, guard, ordering relation, and involved symbols. Represent bindings, calculations, calls, returns, mutation, loops, pattern alternatives, cleanup, capabilities, and checked errors explicitly.
+2. Plan documents by module and declaration, and explain each body in its actual control structure. A declaration overview can precede its detailed behavior; branches and repeated actions should remain recognizable in paragraphs. Paragraph breaks are useful boundaries for changes in scope or topic.
+3. Aggregate adjacent compatible clauses. Combine shared subjects or predicates, introduce a value once, and use unambiguous references afterward. Keep quantified repetition, negation, mutually exclusive alternatives, and early returns explicit. Repeated calls are distinct events even when their text matches.
+4. Use a controlled lexicon and grammar. Render equality, assignment, comparison, indexing, conditional execution, iteration, and error propagation with stable terminology. Treat names as names; retain an identifier or a precise source fragment when linguistic expansion would guess its meaning.
+5. Derive dependency surfaces from resolved usage: called declarations, referenced values, accessed members, referenced types and constructors. Imports alone do not prove a surface is used. Aliases must resolve to their original declaration. Define separately whether type-only usage belongs in the dependency section.
+6. Link a dependency at its use and provide one canonical description of its used contract. Explain local call arguments, return handling, state changes, and failure handling locally. Avoid recursively narrating an entire dependency implementation. If symbol resolution or documentation is unavailable, state that boundary explicitly without inventing behavior.
+7. Make determinism explicit: fixed traversal and ordering, fixed grammar rules, canonical links, no random variation or remote generation, and no timestamps or environment-specific paths in the output. Equal compiler inputs and generator version should produce equal bytes. This is a project contract requiring tests, not a research guarantee.
+8. Preserve a coverage ledger through planning and aggregation. Every required source fact must be realized or deliberately accounted for. Aggregated clauses should retain all contributing fact identities. This makes missing local behavior inspectable without forcing one sentence per AST node.
+
+## Validation criteria
+
+Use independent gates for factual coverage, faithfulness, readable prose, dependency scope, valid links, and reproducibility. Representative fixtures should include nested alternatives, early exit, loops, local mutation, errors, callbacks, aliases, overloaded or ambiguous references, type-only dependencies, and repeated effects. A sentence snapshot alone cannot prove behavior coverage.
+
+For prose quality, ask readers to recover inputs, outputs, branching, state changes, errors, and the role of dependencies from the generated document. Review sentence-level truth separately from paragraph coherence and excessive detail. The literature supports these as useful evaluation directions; it does not establish that a compiled prose document replaces executable semantics, formal verification, domain requirements, or handwritten explanations of design intent.

package/docs/research/ecosystem-workflow.md

@@ -0,0 +1,41 @@
+# Project creation, Git packages, and editor help
+
+Research checked September 30, 2026. This note separates behavior documented by the source projects from recommendations for August. Proposed commands and import forms below are design examples, not a claim that they are implemented.
+
+## What to borrow from Go
+
+Go lets an author distribute a module through its source repository. The module path identifies its location, and release tags identify versions. Consumers can discover dependencies from their imports and fetch the source into a cache. A repository can contain several modules, although one module at its root is the simpler authoring path. [Go: managing module source](https://go.dev/doc/modules/managing-source)
+
+Go accepts revision queries such as a branch or commit at the command line, then records a canonical version. Its pseudo-versions preserve a particular revision when no release tag exists. Modules can live in repository subdirectories, with a corresponding tag prefix. Cached source is checked against hashes; Go also has a public checksum database. These are separate mechanisms: storing a hash locally does not establish the publisher's identity or reproduce that database's protections. [Go modules reference](https://go.dev/ref/mod#versions), [module subdirectories](https://go.dev/ref/mod#vcs-dir), [module authentication](https://go.dev/ref/mod#authenticating)
+
+Publishing a Go release includes testing, creating a new version tag, and pushing it. Its documentation tells authors to publish a new version rather than change an existing release. [Go: publishing a module](https://go.dev/doc/modules/publishing)
+
+**Recommendation for August:** make a public HTTPS Git repository enough to share a library. An author should need August source, `export.aug`, one August manifest, a license, and a release tag. Keep npm archives as an additional transport, without requiring an npm account or a duplicate npm manifest for Git packages. Teach one ordinary author-to-consumer path before explaining transport alternatives.
+
+For consumers, put the location where the dependency is used. A quoted source such as `import add from "https://github.com/example/math#v0.1.0"` is one possible form. A short package alias can remain useful when many files import the same library; let a command generate its configuration instead of making the reader maintain the mapping by hand. Avoid spelling the same URL and version in both source and configuration unless they serve different purposes.
+
+Resolve a tag or branch to an exact commit during installation, and retain that commit, the selected repository subdirectory, and a source digest in `aug.lock.json`. A matching lock should restore that snapshot rather than follow a moved branch. Make dependency updates explicit. Continue to keep ordinary checking read-only and let `aug run` prepare missing snapshots. Distinguish “available offline” from “first download verified against a previously trusted digest.”
+
+Git can list a remote's references and object IDs without a working-tree checkout. Annotated tags have both tag and peeled-object entries, so the resolver must retain the commit target. [Git: ls-remote](https://git-scm.com/docs/git-ls-remote)
+
+Use subprocess argument arrays, validate repository paths and revision selectors, and disable dependency hooks. Preserve August's source-boundary and symlink checks. These are implementation recommendations, not security guarantees supplied by Go.
+
+Move optional August libraries through the same consumer path, using actual package directories in the existing public repository. Keep compiler/runtime primitives in the toolchain. The migration must retain native adapter compatibility and make the weather starter work from an installed CLI without a language-repository checkout.
+
+## The familiar weather API
+
+Microsoft's ASP.NET Core web API template provides `GET /weatherforecast`. Its minimal API implementation returns five forecasts with a date, Celsius temperature, summary, and computed Fahrenheit temperature. It generates simulated values, rather than calling a weather provider. Startup, the route, and the response record are visible in its generated `Program.cs`. OpenAPI registration and its development endpoint are included when enabled. [Microsoft's minimal API template source](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/WebApi-CSharp/Program.MinimalAPIs.WindowsOrNoAuth.cs)
+
+Microsoft's onboarding creates a project, runs it, opens the forecast route, and inspects the returned JSON. The tutorial also explains the generated OpenAPI document. [Microsoft: create a web API](https://learn.microsoft.com/en-us/aspnet/core/tutorials/first-web-api?view=aspnetcore-10.0)
+
+**Recommendation for August:** offer a weather template through the installed CLI and npx, then continue with `aug run`. Keep the recognizable route and response fields. Use deterministic sample forecasts so the guide, tests, and compiled explanation agree. Say plainly that the data is simulated. Put startup in `main.aug`, the typed response and forecast operation beside their tests, and the endpoint in a nearby file if separating it helps the lesson. Include an HTTP request file, the expected JSON, OpenAPI configuration, and `AGENTS.md` with the project's own checking/spec commands. Demonstrate one change and its test after the initial successful request.
+
+## Completion and suggested fixes
+
+VS Code completion items accept a `SnippetString`, explicit replacement ranges, documentation, and sorting/filtering text. Additional text edits can insert an import when a completion is accepted; they must not overlap the main edit or one another. Set sorting and insertion fields in the initial result, because resolving an item later must not change them. [VS Code API: CompletionItem](https://code.visualstudio.com/api/references/vscode-api#CompletionItem)
+
+Code actions should apply to the requested range. A quick fix can carry its diagnostic, a workspace edit, and `isPreferred` when it resolves the underlying problem. Providers should declare their supported action kinds so VS Code can avoid unnecessary requests. [VS Code API: CodeAction](https://code.visualstudio.com/api/references/vscode-api#CodeAction), [CodeActionProvider](https://code.visualstudio.com/api/references/vscode-api#CodeActionProvider)
+
+Snippets appear in IntelliSense and the snippet picker. `editor.tabCompletion` enables insertion from a typed prefix, and numbered placeholders allow navigation through editable fields. [VS Code: snippets](https://code.visualstudio.com/docs/editing/userdefinedsnippets)
+
+**Recommendation for August:** rank visible locals and members first, offer named argument placeholders, complete import paths and public exports, and attach Javadoc to suggestions. Add context-specific snippets for records, interfaces, implementations, endpoints, tests, error handling, tasks, and ownership scopes in the project's chosen block style. Offer fixes for misspelled visible names, missing public imports, mislabeled arguments, and absent interface members. A fix must make the program more correct; an “Explain error” action is useful help but should not be presented as a repair. Exercise these workflows against unsaved and incomplete source, since that is where users invoke completion.