@greenpandastudios/aug-cli 0.19.0

package/docs/testing.md

@@ -0,0 +1,120 @@
+# Built-in unit tests
+
+Tests live in the same file as the declaration they describe. Class suites use `test ClassName subject`; function suites use `test functionName`. Tests are excluded from production executables, and no test package is required.
+
+Endpoint suites use `test endpoint endpointName client`. HttpTestClient enters the native routing and policy pipeline with explicit method, relative path, headers and optional Bytes body. Group bindings supply fresh test dependencies; production startup is excluded. See the [complete service and endpoint cases](web.md#endpoint-tests). Live sockets, TLS negotiation and disconnect behavior require transport tests separately.
+
+## A complete function suite
+
+```aug project=testing-guide file=main.aug
+import add from math
+
+print(value=add(left=1, right=2))
+```
+
+```aug project=testing-guide file=fixtures.aug
+/** A reusable, pure test input. */
+fixture seven() returns int:
+    return 7
+```
+
+```aug project=testing-guide file=math.aug
+import seven from fixtures
+
+/**
+ * Add two integers with defined wrapping.
+ * @param left First operand.
+ * @param right Second operand.
+ * @return Their sum.
+ */
+add(int left, int right) returns int:
+    return left + right
+
+test add:
+    when addition:
+        it adds for (left, right, expected) in [(1, 2, 3), (4, 3, 7), (0, 0, 0)]:
+            assert(add(right=right, left=left) == expected)
+
+        it uses_fixture:
+            assert(add(left=seven(), right=0) == 7)
+```
+
+Each tuple row becomes a separately listed and executed case. Row arity and types are checked. The row variables are local to that case. Fixtures are ordinary checked functions marked `fixture`; import them explicitly and declare any dependencies/effects. They create no implicit fixture scope and remain callable as ordinary functions.
+
+## A complete class suite
+
+```aug project=class-testing-guide file=main.aug
+import Counter from counter
+
+counter = Counter(initial=1)
+print(value=counter.value())
+```
+
+```aug project=class-testing-guide file=counter.aug
+interface Count:
+    increment() changes self
+    value() returns int
+
+Counter(mutable int initial to _count) implements Count:
+    increment() changes self:
+        _count = _count + 1
+    value() returns int:
+        return _count
+
+test Counter counter:
+    when increment:
+        counter = Counter(initial=3)
+        it advances:
+            borrow counter:
+                counter.increment()
+            assert(counter.value() == 4)
+        it starts_fresh:
+            assert(counter.value() == 3)
+```
+
+The subject header identifies a local class and the variable used to test it. It does not invoke the constructor; initialize that subject in setup or the case. Generic classes use concrete type arguments. Tests follow ordinary member privacy and cannot access private fields merely because they share the file.
+
+## Groups, setup, and dependencies
+
+Group/case names are identifiers or quoted strings. A suite's groups are unique; a group's cases are unique. Within a group, place bindings or included compositions first, setup statements second, and cases last. Nested groups are not supported.
+
+Every case gets its own setup, bindings, native process, managed heap, and assertion state. Production main bindings and startup never run. Setup variables are visible only to that case. All bindings use ordinary graph, lifetime, and purity checks.
+
+Resolve expressions belong in setup. Test bodies and helpers receive visible dependencies through setup variables or headers. A test can explicitly replace a capability with a private adapter. See [the runnable calculator tests](../examples/developer-workflow/calculator.aug).
+
+Process isolation does not reset files, databases, sockets, or other external resources. Use explicit adapters or case-specific resources for integration tests.
+
+## Assertions and failure
+
+`assert(condition)` and `assert(condition=condition)` require a bool. A failed assertion reports file, line, and source condition. Catching its error cannot make the case pass. Setup may assert its invariants, but every case body must also execute an assertion. A body that executes none fails.
+
+An uncaught checked error, a native crash, a nonzero exit, or a timeout fails the case. Assertions are test operations, not production contracts.
+
+## CLI and coverage
+
+Use `aug` when installed, or `node bin/aug.mjs` from this repository.
+
+| Command | Action |
+| --- | --- |
+| `aug test PROJECT` | Run all cases. |
+| `aug test PROJECT GROUP_NAME` | Select an exact group name. |
+| `aug test PROJECT --group NAME` | Same explicit selection. |
+| `aug test PROJECT --list --json` | Discover IDs, subject, group, case, row, file, and line. |
+| `aug test PROJECT --case ID` | Select an exact ID; repeat for several. |
+| `aug test PROJECT --json` | Machine-readable pass/fail counts and captured output. |
+| `aug test PROJECT --timeout 2000` | Limit each native execution to 2 seconds. |
+| `aug test PROJECT --coverage` | Merge executed statement lines across selected cases. |
+
+Selection is exact and case sensitive. Quote names containing spaces. Unknown selections fail. The default timeout is ten seconds per native case; compilation is outside that timeout.
+
+Test C and binaries live under `.aug-build/tests/`. Coverage writes `.aug-build/coverage/coverage.json` and `lcov.info`, retaining zero-count executable lines in the compiled test closure. It reports statement lines, not branch coverage. Production startup is omitted, so the result is not whole-application startup coverage. Filtering reports only selected tests and their reachable declarations.
+
+`aug check` checks production and test bodies. `aug test` checks selected tests and their reachable declarations; it does not execute or type-check production startup. A test project still has a root main.aug.
+
+## VS Code
+
+Test Explorer groups cases by project, declaration, and when group. Parameterized rows have separate entries and source locations. Saving refreshes discovery; **AugScript: Refresh Tests** refreshes it manually. Running saves pending edits first. Cancellation skips remaining cases after the active case finishes or times out.
+
+Choose **Native tests** to run or **Native coverage** to see merged statement-line coverage when the installed VS Code supports its coverage API. **AugScript: Test Project** runs the project CLI in a task terminal.
+
+The adapter uses the [VS Code Testing API](https://code.visualstudio.com/api/extension-guides/testing). `try`/`always` performs explicit cleanup; snapshots and nested groups are not part of this version. Each selected case currently compiles a separate native binary.

package/docs/tooling.md

@@ -0,0 +1,197 @@
+# Native builds and developer tooling
+
+## CLI
+
+Use `aug` if installed or `node bin/aug.mjs` from the repository. Commands take a project folder, defaulting to the current directory. Editor commands also accept --file and --offset; use --help for the command inventory.
+
+| Command | Output |
+| --- | --- |
+| `check PROJECT [--json]` | Production, tests, module policy, documentation, and configuration diagnostics. |
+| `build PROJECT [--out NAME] [--json]` | Native path; JSON contains output and sourceMap. |
+| `run PROJECT -- args...` | Builds and runs; program stdout is preserved. |
+| `emit-c PROJECT` | Generated C for inspection. |
+| `format PROJECT [--file PATH] [--write] [--json]` | Canonical source; --write updates files. |
+| `migrate PROJECT [--file PATH] [--write] [--json]` | Verified migration of rejected legacy syntax; preview by default. |
+| `spec PROJECT [--check] [--json]` | Adjacent Markdown specs and offline dependency explanations; --check detects drift without writing. |
+| `test PROJECT [--coverage] [--json]` | Isolated native tests and optional statement-line report. |
+| `bench PROJECT [--iterations N] [--warmup N] [--timeout MS] [--json] -- args...` | Release build with timed native executions. |
+| `explain PROJECT --file PATH [--name NAME]` | Checked contracts, dependencies, layers, origins, tests, and module surface. |
+| `context PROJECT --file PATH [--name NAME] [--budget N]` | Bounded JSON context, including related declarations and source snippets. |
+| `lsp PROJECT` | Persistent language server over stdio. |
+| `package init DIRECTORY --name @owner/name` | Standalone source library with public exports, Javadoc and a same-file test. |
+| `package pack DIRECTORY` | Checked source archive ready for npm publishing or local installation. |
+| `install PROJECT [--frozen] [--offline]` | Explicit dependency snapshot and aug.lock.json. |
+
+Warnings are nonblocking. Machine diagnostics carry severity, code, file, line, column, and message. check/build fail on errors; invalid command usage returns nonzero. Test failure returns nonzero and includes the case output.
+
+## Native standard libraries
+
+Web, crypto, JSON and tasks use pinned private C dependencies. On macOS or Linux, bootstrap them once from the compiler directory:
+
+```sh
+node scripts/bootstrap-native.mjs
+```
+
+The script verifies archive SHA-256 hashes and builds under `.aug-native`; it does not install system packages. `--extract-only` supplies yyjson and minicoro for JSON/task-only programs. Web and crypto require the complete native build. Sources, dependency revisions and hashes are recorded in scripts/native-dependencies.lock.json; the installed manifest also records host platform and architecture. The full build has run on macOS ARM and Linux ARM; Linux x86-64 is checked by the Docker CI job.
+
+Set `AUG_NATIVE_HOME` to share a dependency directory across compiler copies. It names the directory containing `sources/` and `prefix/`, not the prefix itself. Bootstrap and compilation both honor it. For the bundled VS Code compiler, set `augscript.nativeHome` to that same absolute directory. The extension bundles the bootstrap scripts and lockfile; it does not bundle host-specific native libraries. Node 24+ and a C11 compiler remain requirements.
+
+The [web guide](web.md) covers transport/TLS/OpenAPI configuration and the working login app. The [gap ledger](web-library-gaps.md) records remaining native and language coverage.
+
+## Configuration
+
+main.yaml is optional. The supported subset has scalar key/value lines and indented dash lists; it is not a general YAML implementation.
+
+```yaml
+output: application
+optimization: debug
+block_style: indent
+indentation: tabs
+assignment: to
+spec:
+  require_comments: none
+strict_modules: false
+max_public_symbols: 12
+max_dependencies: 8
+lint:
+  - wildcard_imports
+  - public_helpers
+  - public_docs
+  - broad_errors
+  - discarded_errors
+  - architecture
+module_dependencies:
+  - ".: app, contracts"
+  - "app: contracts, shared"
+libraries:
+  - m
+library_paths:
+  - native/lib
+```
+
+| Key | Contract |
+| --- | --- |
+| output | Executable name under .aug-build, or an absolute output path. |
+| optimization | debug (-O0) or release (-O2); both retain debug information. |
+| block_style | Formatter braces or indent. |
+| indentation | Formatter spaces (four) or tabs. |
+| assignment | Formatter equals or to; both remain accepted source forms. |
+| spec.require_comments | Require Javadoc on none (default), public declarations/methods, or all declarations/methods. Inherited method docs satisfy it. |
+| strict_modules | Require sibling declarations to be listed in the folder export file. |
+| max_public_symbols | Public declaration/member warning threshold, default 12. |
+| max_dependencies | Import fan-out warning threshold, default 8. |
+| lint | Optional warnings listed above. |
+| module_dependencies | Allowed folder edges; same-folder imports and standard capabilities are allowed. |
+| libraries / library_paths | Linker library names and project-relative search directories. |
+
+An owner without a rule is unrestricted. . names the project root; folder names use slash paths. * matches any folder, and domain/* matches that folder and descendants. Rules use the first matching owner. Import cycles are always rejected independently of the policy.
+
+Unknown/duplicate keys, invalid values, and unsupported list shapes fail during check. VS Code provides key help and completion. Architecture warnings count public surface and dependency fan-out; there is no file-length rule.
+
+## Numeric and text contracts
+
+- int is a signed 64-bit integer. Literals are checked exactly. +, -, multiplication, and negation wrap in two's-complement arithmetic. The minimum divided by -1 also wraps to the minimum. Integer comparison preserves values beyond floating-point precision.
+- Division by a potentially zero operand raises checked ArithmeticError. A known nonzero integer literal divisor does not need that clause.
+- float uses C double. Literals must be finite. Mixed int/float arithmetic widens to double and can lose integer precision. Runtime floating-point results follow native double behavior.
+- c_int is signed 32-bit and maps to the platform C int, whose width is checked during compilation. c_int(value=wide) raises ConversionError outside its range; int(value=narrow) widens without loss.
+- Source strings are Unicode text, emitted as UTF-8. NUL and unpaired surrogates are compile errors. File text rejects embedded NUL and malformed/overlong UTF-8 as FileError. Binary files need a future byte API.
+- Immutable tuples and records have structural equality/hashing. Behavioral classes and mutable collection objects have identity equality. Map/Set preserve insertion order for iteration.
+
+## C boundary
+
+The programmer can expose a C declaration through the language, then wrap it in an ordinary callable with a visible effect contract:
+
+```aug project=ffi-guide file=main.aug
+import announce from native
+
+announce(message="Hello from C")
+```
+
+```aug project=ffi-guide file=native.aug
+extern C puts(string value) returns c_int
+
+announce(string message) uses C.puts:
+    unsafe:
+        result = puts(value=message)
+```
+
+| AugScript | C ABI |
+| --- | --- |
+| int | int64_t |
+| c_int | int, checked as 32 bits |
+| float | double |
+| bool | bool |
+| string | const char* (UTF-8, no NUL) |
+| void | void |
+
+C calls require unsafe, and callables declare uses C.function. Ordinary scalar extern declarations have no generics, resolve parameters, ownership transfer, nullable boundary types, or checked error clause. For libc functions taking C int, explicitly narrow with c_int; do not declare their boundary as int64_t.
+
+Standard adapters use `extern C value` for the managed AugValue ABI. Each C argument and result must actually be AugValue; headers expose the declared capability effect and checked failures. `pure` asserts a trusted native implementation has no observable effects. These declarations are unsafe contracts, not automatic C bindings. Crypto, HTTP, JSON and time adapters demonstrate this narrow boundary in src/stdlib and runtime.
+
+The extern declaration must match the real native ABI. This version does not expose pointers, callbacks, binary buffers, arbitrary structs, or a C header importer.
+
+## Source locations and debugging
+
+Native output lives under .aug-build. Generated C has #line locations for executable AugScript statements and extern declarations. Native compiler errors at those locations become NATIVE diagnostics. A successful build writes EXECUTABLE.augmap.json with compiler version, exact C arguments, source hashes, generated hash, and symbol origins.
+
+Every build uses -g. Use **Debug AugScript** in VS Code with LLVM lldb-dap on PATH, or configure augscript.lldbDapPath. The extension builds the project and launches the standard adapter. See the [VS Code debugger API](https://code.visualstudio.com/api/extension-guides/debugger-extension) and [LLDB DAP documentation](https://lldb.llvm.org/use/lldbdap.html).
+
+**AugScript: Debug in LLDB Terminal** works with an ordinary lldb executable. Example terminal commands:
+
+```text
+breakpoint set --file /absolute/project/domain/numbers.aug --line 20
+run
+bt
+```
+
+Debug information resolves source breakpoints. Variables currently display the C runtime's tagged representation; rich AugScript variable views, expression evaluation, and ownership-aware debugging are future work. This machine has LLDB but no lldb-dap, so the DAP launch path requires installing/configuring that adapter. The source-breakpoint smoke test resolved two locations; native launch then stalled on this host and was stopped, so interactive stepping and call-stack behavior remain unverified here.
+
+AUG_TRACE_DROPS=1 enables runtime cleanup tracing to stderr for lifecycle verification; it is developer instrumentation, not a language I/O capability.
+
+## Benchmarks
+
+`aug bench` compiles release C, runs warmups, then reports every sample, median, minimum, and p95 in milliseconds. Measurements include process startup and exclude compilation. The timeout bounds each native run.
+
+See [performance and benchmark graphs](performance.md) for measured comparisons with C, Node and Python, peak memory, HTTP throughput, raw results, and reproducible commands. `npm run bench:compare` measures the fixed workloads under `benchmarks/`. The earlier [single-workload baseline](benchmarks.json) is preserved as historical evidence.
+
+The runtime uses tagged values, dynamic member lookup, a managed heap, and runtime collection adapters. Speed claims require workload comparisons and profiling; translating to C alone does not establish them.
+
+## Context for developers and LLMs
+
+Explain emits checked callable inputs, results, mutation, capabilities, effective errors, interceptor order/dependencies/short-circuit signals, source locations, tests, and binding lifetimes. Endpoint contracts also include route, status, streaming, wire input sources, policy options and explicit policy dependencies. Context adds reachable related declarations and source snippets within a character budget (512–100000, default 12000).
+
+Output labels completeness as checked or partial and marks truncation explicitly. A partial or truncated result cannot establish whole-application correctness. Provenance uses stable declaration IDs and absolute source locations.
+
+Save a report, then compare architecture with --baseline previous.json. Reports include file dependency edges, public signature hashes, and member counts; changes describe added/removed dependencies and public interface growth. Both reports must cover the modules being compared.
+
+## Persistent editor checks and reproducibility
+
+### File icons
+
+The VS Code extension includes an August logo and a file icon theme. Run
+**AugScript: Open Welcome** for the illustrated overview and guides; its images
+are bundled and work offline. Run
+**AugScript: Enable File Icons** to select it for the current workspace, or use
+**Preferences: File Icon Theme → AugScript Icons**. The repository already sets
+`workbench.iconTheme` to `augscript-icons` in its workspace settings.
+
+| File | Icon meaning |
+| --- | --- |
+| `.aug` | Blue source file. |
+| `main.aug` | Amber startup file. |
+| `export.aug` | Purple public module surface. |
+| `main.yaml` | Teal project configuration. |
+
+Default light/dark language icons also work with compatible icon themes. The
+August theme provides the special startup and export marks. After installing an
+updated VSIX, use **Developer: Reload Window** if the editor still displays the
+previous version. Editable vector artwork and its rendering instructions live
+in `vscode/media`.
+
+### Language server
+
+The language server implements the [LSP 3.17 protocol](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/lsp/3.17/specification.md) over Content-Length framed UTF-8 messages. It handles document versions, diagnostics, hover, completion, definitions, formatting, fixes, and semantic tokens.
+
+One server runs per project. Parsed modules and checked import closures are cached by source/configuration revision. Unrelated edits reuse the previous immutable semantic document; dependency edits invalidate its closure. Local files can be checked while main composition is incomplete. Whole-project check/build still validates all bindings and startup.
+
+Compiler and extension development dependencies use exact versions and lockfiles. Native maps record the selected C toolchain and inputs; C compiler/OS versions are environment requirements, not vendored binaries. User-authored source packages use npm archives/registry transport, exact versions, and `aug.lock.json`; [the package guide](packages.md) covers creation, installation, public imports and frozen CI builds.

package/docs/web-implementation-plan.md

@@ -0,0 +1,39 @@
+# August web implementation
+
+## Confirmed scope
+
+The user confirmed the language and web design on 2026-09-28 and asked for implementation, with a runnable OpenID Connect login proof. Both the OpenID Connect provider and the relying-party login flow belong in the same August application.
+
+The language tenets are simplicity and developer scalability. Public declarations must show inputs, dependencies, effects, errors, and behavior in context. Imports and module exports remain explicit. Application logic belongs in August; native protocol and cryptographic operations belong behind safe capability interfaces and narrow unsafe adapters.
+
+### Delivery requirements
+
+- C output and pinned libwebsockets/GnuTLS HTTP/1.1, HTTP/2, HTTP/3, and TLS transport.
+- Structured concurrency: scope-owned tasks and DI, start/wait for, ordered grouped and collection waits, always cleanup, cancellation, bounded workers, reference sharing, explicit locks, channels and broadcasts.
+- Named first-party endpoints, typed binding sources, explicit serve selection in main.aug, JSON/HTML/binary and bounded streaming responses, outbound HttpClient, and HttpResponse<T>.
+- JSX-style server components with checked named properties and children. handle endpoint(...) binds an HTTP action. input from form supplies a typed body. Successful actions follow redirects or reload the page. August application code runs on the server; generated transport wires events to requests.
+- Immutable records with immutable collection fields, consuming deep freeze, optional versus nullable states, and private body fields with pure initialization.
+- Checked unless errors, mapped errors, Problem Details, automatic 400/413/415/422 binding responses, request-scoped 500 handling, and termination after streaming has begun.
+- Configurable interceptors in declaration order and explicit authentication capabilities.
+- Strict OpenAPI generation configured in main.yaml, same-file endpoint tests, protocol integration tests, compiler diagnostics, documentation, and VS Code support.
+- august.crypto and a same-application OpenID Connect provider/client proof, issuing a separate application session JWT after validating the provider ID token.
+
+### Agreed public test seams
+
+The confirmed design includes compiler/CLI behavior, same-file endpoint tests through the HTTP pipeline, and actual native protocol tests. The requested proof adds the externally observable login flow: discovery, authorization, code exchange, signature and claim validation, session issuance, protected access, and logout. Cryptographic verification is tested through public capability operations and independently specified vectors.
+
+## Work sequence
+
+1. Establish reproducible native dependencies and record current gaps.
+2. Implement foundational syntax and safe runtime data operations in vertical slices.
+3. Implement endpoint checking, HTTP transport, serialization, response control, and OpenAPI.
+4. Implement server markup, components, forms, and endpoint action transport.
+5. Implement structured concurrency and synchronized scoped resources.
+6. Implement crypto capabilities, JOSE/JWT, and OpenID Connect application modules.
+7. Exercise the native app end to end, address discovered gaps, update tooling, review, and run release gates.
+
+## Proof profile
+
+Authorization Code flow with S256 PKCE, unpredictable state and nonce, exact redirect-URI matching, one-use short-lived authorization codes, a discovery document and JWKS, validated signed ID tokens, and an independently signed expiring application-session JWT in an HttpOnly cookie. Provider and application session credentials have distinct validation contexts. Loopback HTTP is an explicit development configuration; external deployments use TLS.
+
+This file records requirements, not a claim that delivery is complete. Actual verification and remaining gaps are recorded separately.

package/docs/web-library-gaps.md

@@ -0,0 +1,27 @@
+# Web and crypto library gaps
+
+This ledger records gaps discovered while implementing the confirmed web design and the same-application OpenID Connect proof. Status must reflect executable evidence.
+
+| Gap | Why the proof needs it | Status |
+| --- | --- | --- |
+| Native HTTP/TLS transport | Provider and client must exchange real HTTP requests in one app without blocking each other. | HTTP/1.1, TLS peer verification, HTTP/2 and an HTTP/3-only QUIC client pass socket tests. Same-process outbound requests suspend the request task. Independent implementations and broader protocol conformance remain to be exercised. |
+| Typed requests, responses, headers, cookies, redirects and forms | Login, authorization, token exchange, session issuance and logout need explicit protocol control. | The native login flow verifies typed JSON and form input, duplicate-preserving headers, browser cookies and redirects. Multipart forms, inbound streaming and broader HTTP conformance remain. |
+| JSON decoding and length-aware binary/text values | JWKS, tokens, request records, and valid JSON need safe lossless serialization. | Strict parsing, int64 record decoding, value-or-null optional fields and shared frozen collections pass native tests. Omitted optional fields become null. More HTTP input coverage remains. |
+| Cryptographic capabilities | Secure randomness, SHA-256/PKCE, signatures, verification, key handling and constant-time comparison. | Injectable GnuTLS adapter, RSA JWK export/import, fixed-algorithm/type JOSE and PBKDF2 run in the proof. Node independently verifies the provider signature. General secret-buffer zeroization and key lifecycle APIs remain. |
+| Protocol-specific error bodies | OAuth token errors require OAuth JSON rather than the default RFC 9457 body. | Token grant and form failures return OAuth JSON; transport-level limits still use HTTP Problem Details. The response contract is visible in generated OpenAPI. |
+| OpenID Connect protocol support | Discovery, exact client/redirect checks, PKCE, nonce/state, one-use codes, and ID-token validation. | Same-application authorization-code flow passes. Wrong PKCE, replay, tampered JWTs, provider-token/session substitution, protected access and logout revocation pass. Broader provider profiles, account persistence, federation, key rotation and certification remain. |
+| Scoped concurrent state | Authorization transactions and codes need bounded lifetimes and synchronized access. | Bounded ExpiringStore<T> uses Shared<Map<...>> with atomic removal. Scope joining, cancellation, cleanup and task capture loans pass native/compiler tests. Scheduling remains on one OS thread; bounded multicore workers, channels and broadcasts remain. |
+| Server markup and typed HTTP actions | Login forms and protected pages must be authored in August. | Typed components, escaped markup and deferred handle actions pass compiler/socket tests. POST/PATCH/PUT/DELETE forms use generated same-origin event transport. Provider sign-in and app logout pass browser interaction testing with typed actions. Ordinary no-referrer HTML form POST sends a null Origin in this browser; the proof uses actions while preserving strict Origin and CSRF checks. |
+| Same-file endpoint tests and OpenAPI | Public behavior and contracts must remain discoverable and verifiable. | Strict OpenAPI 3.2.1 generation, the served API explorer, and same-file endpoint pipeline tests pass. The test client exercises native routing, binding, DI, serialization, and bounded streaming collection. Editor help and context preserve route, wire source, policy options and endpoint cases. Test transport parsing is not a substitute for socket tests. |
+| Streaming and interceptor policies | Streams need backpressure, cancellation and whole-request policy lifetime. | Yielded SSE, Bytes and Html pass socket tests with a single bounded 64 KiB pending item and transport backpressure. Errors before output map to responses; errors after headers terminate output. TCP disconnect runs always cleanup and request logging. Authentication before decode, permission checks, rate limits, exact-origin CORS/preflight, gzip and streaming deadlines pass native socket tests. Policies currently precede custom parameter interceptors. Inbound streams, request-reception deadlines and broader compression negotiation remain. |
+| Native dependency tooling | Full web/crypto builds need a private native stack on each host platform. | Pinned private bootstrap and native tests pass on macOS ARM and Linux ARM. Linux x86-64 runs in Docker CI. The build and runtime images include matching native libraries; other platforms remain unverified. |
+| Public task error contracts | Task helpers should show their delayed failures in context. | Locally scheduled errors follow task aliases, collections, waits, exception paths and implicit joins. A helper accepting Task<T> must handle or declare Error; a public type spelling for a narrower delayed-error contract remains. |
+| Injected captures and owned shared payloads | Concurrent helpers must preserve dependency loans and resource lifetime. | The compiler tracks task reads through injected dependencies as well as written arguments and receivers. A native regression verifies that dropping an owned `Shared<T>` drops its transferred payload before later locals. Broader ownership and cancellation conformance work remains in the language roadmap. |
+
+Release review regressions cover duplicate scalar query/header/cookie/form inputs without process failure, inherited child deadlines, lock progress, owned resource lifetime, sibling and grouped cleanup errors, bounded response statuses, int64 action captures, complex and Json-valued forms, empty streams, and post-yield endpoint-test failures.
+
+## Scope boundaries
+
+The proof is a development identity provider in the same application as its relying party. Identity-provider certification, persistent account management, federation, key rotation, and distributed session revocation require explicit follow-up work unless delivered and verified here. The provider must still implement the protocol checks used by its declared flow.
+
+Multicore worker and channel/broadcast patches were rejected by automatic approval review because their execution, ownership and wakeup changes affect the runtime broadly. Those patches were not applied. Explicit approval requests remain pending; scheduling remains on one OS thread.

package/docs/web.md

@@ -0,0 +1,197 @@
+# HTTP, server pages, and crypto
+
+HTTP endpoints are language declarations. `august.web` supplies explicit network, authentication, authorization, and logging capabilities; `august.crypto` supplies cryptographic adapters. August source owns routing contracts and application decisions. The native boundary owns transport, serialization, and cryptographic primitives.
+
+## A complete service
+
+This project serves a protected JSON endpoint, an August page, a form action, and an event stream. The documentation gate builds it and runs its endpoint cases without starting a persistent server. Copy the files into one folder and run `aug run FOLDER` to listen on port 8080.
+
+```aug project=web-guide file=main.aug
+import readUser and events from api
+import home from pages
+import save from actions
+import DemoAuthentication from auth
+import Authentication and RequestLogger and WebRequestLogger from august.web
+
+implement Authentication with DemoAuthentication
+implement RequestLogger with WebRequestLogger scoped
+serve readUser and events and home and save on port 8080
+```
+
+```aug project=web-guide file=models.aug
+record User(int id, string name)
+record UserInput(string name)
+```
+
+```aug project=web-guide file=auth.aug
+import Authentication and Principal from august.web
+
+/** A demonstration adapter. Replace its credential check for a real application. */
+DemoAuthentication() implements Authentication:
+    authenticate(HttpRequest request) returns optional Principal uses Authentication.authenticate unless HttpError:
+        match request.headers.get(name="authorization"):
+            when null:
+                return null
+            when some value:
+                if value == "Bearer demo":
+                    return Principal(subject="ada", permissions=["users.read"])
+                return null
+```
+
+```aug project=web-guide file=api.aug
+import User from models
+import DemoAuthentication from auth
+import Authentication and RequestLogger and WebRequestLogger from august.web
+
+/** Look up one user. Authentication runs before the identifier is decoded. */
+[LogRequest(logger=logger)]
+[RequireLogin(authentication=auth)]
+[RateLimit(requests=100, seconds=60)]
+[Timeout(milliseconds=1000)]
+[Compress]
+endpoint GET "/users/{id}" as readUser(int id from path, resolve Authentication auth, resolve RequestLogger logger) returns User uses auth.authenticate and logger.complete:
+    return User(id, name="Ada")
+
+test endpoint readUser client:
+    when requests:
+        implement Authentication with DemoAuthentication
+        implement RequestLogger with WebRequestLogger scoped
+        it requires_identity_before_decoding:
+            response = client.request(method="GET", path="/users/not-an-integer")
+            assert(condition=response.status == 401)
+        it returns_a_user:
+            headers = Headers().with(name="authorization", value="Bearer demo")
+            response = client.request(method="GET", path="/users/7", headers)
+            assert(condition=response.status == 200)
+            assert(condition=response.body.text() == "{\"id\":7,\"name\":\"Ada\"}")
+
+/** Each yield waits for transport capacity; disconnect cancels the producer. */
+endpoint GET "/events" as events() streams ServerEvent<User> unless HttpError:
+    yield ServerEvent(data=User(id=1, name="Ada"), event="user", id="first")
+    yield ServerEvent(data=User(id=2, name="Grace"), event="user")
+
+test endpoint events client:
+    when streaming:
+        it returns_events:
+            response = client.request(method="GET", path="/events")
+            assert(condition=response.status == 200)
+            assert(condition=response.headers.get(name="content-type") == "text/event-stream")
+```
+
+```aug project=web-guide file=actions.aug
+import UserInput from models
+import redirect from august.web
+
+/** Accept a typed form and redirect after handling it. */
+endpoint POST "/users" as save(UserInput input from form) returns HttpResponse<string> unless HttpError:
+    return redirect(location="/")
+```
+
+```aug project=web-guide file=views.aug
+import User from models
+import save from actions
+
+UserCard(User user) returns Html:
+    return <article><h2>{user.name}</h2><p>User {user.id}</p></article>
+
+NewUser() returns Html unless HttpError:
+    return <form onSubmit={handle save(input from form)}><label>Name <input name="name" required /></label><button type="submit">Save</button></form>
+```
+
+```aug project=web-guide file=pages.aug
+import User from models
+import UserCard and NewUser from views
+
+/** Render checked components; interpolated text and attributes are escaped. */
+endpoint GET "/" as home() returns Html unless HttpError:
+    return <html><head><title>August users</title></head><body><UserCard user={User(id=7, name="Ada")} /><NewUser /></body></html>
+```
+
+Use POST, PUT, PATCH, or DELETE for a write action. `handle remove(id=user.id)` describes a deferred HTTP request; it does not call `remove` while rendering. `input from form` maps form fields to a checked record. The generated same-origin browser transport submits the selected endpoint, follows its redirect, reloads successful writes, and displays failures as text. There is no August browser compiler in this version.
+
+Captured values and form inputs preserve signed 64-bit integers, including identifiers beyond JavaScript's safe integer range. A form field containing a record, collection, or `Json` uses JSON text; for example, `[1,2]`, `{"id":7}`, or `"Ada"` for a string-valued `Json`. Ordinary string fields contain plain text. The transport encodes fields according to their declared types.
+
+## Wire contracts and responses
+
+Every ordinary endpoint input states its source: `from path`, `from query`, `from header`, `from cookie`, `from body`, `from form`, or `from request`. A source can specify a wire name. `resolve` inputs come from the application's explicit DI composition. Only endpoints selected by `serve` are reachable over HTTP.
+
+JSON bodies decode into concrete immutable records. `optional T` allows a value or null. Omitted optional fields and inputs become null, including PATCH bodies. Match null/some before reading the value. Serializing a record includes null optional fields; it does not recreate whether a field was originally omitted. Unknown or incorrectly typed record fields are rejected. An absent required query/header/form value and invalid scalar syntax return 400; invalid JSON syntax returns 400, a valid JSON schema mismatch returns 422, unsupported media returns 415, and an oversized body returns 413.
+
+An ordinary return becomes the documented status and a JSON, Html, or Bytes representation. `HttpResponse<T>` selects status and immutable `Headers` explicitly. `Headers.with` appends a value, preserving repeated headers such as Set-Cookie; singular wire inputs reject duplicates. The `redirect` and `cookie` helpers validate header values. Cookie callers explicitly choose Secure and lifetime settings.
+
+Response status literals must range from 200 to 599; constructing a response with a dynamic status requires handling or declaring `HttpError`. Complex form fields use the same JSON schemas as body inputs: malformed JSON text returns 400 and a schema mismatch returns 422.
+
+`unless ErrorType with status CODE` declares an error response. Unexpected failures produce 500 with server-side error reporting. Default failures use [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html). OAuth endpoints in the proof return their protocol's JSON errors explicitly. HEAD suppresses the body; 204 and 304 suppress body and Content-Length. See the [gap ledger](web-library-gaps.md) for unimplemented HTTP behavior; this is not a claim of full protocol conformance.
+
+## Policies and interceptors
+
+The first written HTTP policy is outermost. Policies execute before wire decoding; custom parameter interceptors execute after decoding. The compiler requires all HTTP policies before custom interceptors. Put `LogRequest` first to observe failures rejected by later guards.
+
+| Policy | Inputs and behavior |
+| --- | --- |
+| RequireLogin | `authentication=auth` maps an explicit `resolve Authentication auth`; declare `uses auth.authenticate`. A null identity returns 401. The adapter validates credentials. |
+| RequirePermission | Maps Authentication and Authorization dependencies plus a literal permission; denied access returns 403. Declare both capability operations. |
+| LogRequest | Maps `resolve RequestLogger logger` and `uses logger.complete`. Calls completion in reverse layer order after transport completion or disconnect. Disconnect status is 499 for logging. WebRequestLogger emits escaped JSON metadata without credentials or query strings. |
+| RateLimit | Literal requests and seconds; a bounded fixed-window counter per endpoint and trusted transport peer. It ignores client-supplied forwarding headers. Excess returns 429. |
+| Timeout | Literal milliseconds; handler, scoped tasks, streaming and transport share the deadline. Before output, timeout returns 504; after headers it terminates output. C calls finish before cooperative cancellation is observed. Buffered request reception precedes this deadline. |
+| Cors | Literal exact origins, optional request-header allowlist and credentials. A supplied disallowed origin returns 403. Preflight checks the selected route's method and requested headers. Wildcard cannot enable credentials. CORS is not authentication or CSRF protection. |
+| Compress | Negotiates gzip, respects an existing Content-Encoding, and skips bodyless statuses. Stream items use complete concatenated gzip members as permitted by [RFC 1952](https://www.rfc-editor.org/rfc/rfc1952.html). |
+
+Options are compile-time literals; dependency mappings must reference the canonical `august.web` capabilities. Cors and Compress may each appear once. Multiple deadlines choose the earliest. Custom interceptors retain their checked around/next contracts and written order.
+
+## Streams and scoped tasks
+
+An endpoint may `streams ServerEvent<T>`, `streams Bytes`, or `streams Html`. `yield` supplies one item. Each pending encoded item is bounded to 64 KiB and sent under transport backpressure. A response has one consumer. Errors before headers become HTTP responses; later failures terminate output without appending a second error representation. Disconnect cancels the request and its children; `always` cleanup runs. The request DI scope survives through response completion.
+
+`start fetch(...)` creates a task owned by its lexical scope. `wait for loadingUsers and loadingOrders to users and orders` waits in the stated result order; `wait for taskList` returns an ordered result list. `to`, `as`, and `=` result assignments are supported where the grammar permits them. Scope exit joins children; an unhandled child failure cancels siblings. Read-only frozen values can be shared without copying. Mutable captures are loaned until the task is observed. `lock shared as value` grants exclusive mutation and forbids nested locks, I/O, task starts and waits inside the locked region.
+
+Declare an owned resource directly in its task's `scope` block to keep it alive through implicit joining. A resource declared in a shorter nested block must be waited for before that block ends; the compiler rejects a live task borrow at that boundary. Unrelated owned cleanup does not join the enclosing scope's children. Pure loops under a lock finish or observe cancellation before another coroutine runs.
+
+Scheduling checks receiver and argument errors immediately. A scheduled callee's errors are checked at waits and implicit joins. A wait can observe an unhandled sibling failure; grouped and collection waits finish observing every selected child before rethrowing the first error. Catch around the entire scope when handling failures from children that are not explicitly observed.
+
+Scheduling currently uses cooperative coroutines on one OS thread. Outbound HttpClient I/O suspends the coroutine, so the same executable can call its own endpoints. Multicore workers, bounded channels/broadcasts, and inbound request streams remain gaps. The [gap ledger](web-library-gaps.md) records delivery status.
+
+## OpenAPI configuration
+
+Add to main.yaml:
+
+```yaml
+web:
+  host: 127.0.0.1
+  body_limit: 1048576
+  response_limit: 4194304
+  http3: false
+openapi:
+  enabled: true
+  title: August users
+  version: 1.0.0
+  path: /openapi.json
+  docs: /docs
+  output: .aug-build/openapi.json
+```
+
+`web.tls` accepts certificate, private_key and optional outbound ca paths relative to the project. HTTP/3 requires TLS. Native HttpClient verifies peers and returns redirects for explicit handling. The private bootstrap enables libwebsockets HTTP/1.1, HTTP/2 and HTTP/3 on tested macOS ARM and Linux ARM hosts.
+
+OpenAPI 3.2.1 includes selected endpoints, input sources, concrete record schemas, explicit response variants and Javadoc. Streams have item schemas. Unsupported contracts fail compilation when generation is enabled. `/docs` is the generated API explorer. [OpenAPI 3.2.1](https://spec.openapis.org/oas/v3.2.1.html) is the contract reference.
+
+## Endpoint tests
+
+`test endpoint NAME client` must live with that endpoint. The compiler supplies HttpTestClient; group bindings replace production dependencies explicitly. `client.request` exercises the shared native router, policies, wire binding, DI, handler and serialization. Stream collection is bounded by response_limit. Each case has fresh process state. Production startup is excluded.
+
+This tests the application pipeline; socket parsing, TLS negotiation and transport disconnects need separate live-transport tests. Run `aug test FOLDER requests` to select the example's group. The [testing guide](testing.md) describes rows, filtering and coverage.
+
+## Crypto and the login proof
+
+Crypto is an injected capability with GnuTlsCrypto as its native adapter. It provides OS-backed randomness, SHA-256, constant-time content comparison, strict base64url, opaque RSA keys, RS256 signing/verification, RSA JWK import/export, and PBKDF2-HMAC-SHA256 password derivation. Private RSA material is scrubbed on reclamation; general secret-buffer lifecycle and key rotation APIs remain gaps.
+
+`signJwt` requires an explicit key id and token type. `verifyJwt` accepts the configured RS256/key-id/type profile, rejects unsupported JOSE fields, verifies the signature before exposing claims, and follows no token-provided URL. The consuming protocol still validates issuer, audience, times, nonce and token purpose. The implementation follows the fixed-algorithm approach described in [JWT best current practices](https://www.rfc-editor.org/rfc/rfc8725.html).
+
+The [same-app login example](../examples/oidc-login/README.md) contains an OpenID Connect provider and relying party in one August application. It uses real loopback discovery, authorization, token, JWKS and UserInfo endpoints, Authorization Code with S256 PKCE, browser-bound state/nonce/CSRF, and a distinct application-session JWT with live revocation. The UI signs in and signs out through typed actions. See [OpenID Connect Core validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) and [S256 PKCE](https://datatracker.ietf.org/doc/html/rfc7636).
+
+```sh
+node scripts/bootstrap-native.mjs
+node bin/aug.mjs run examples/oidc-login
+node bin/aug.mjs test examples/oidc-login --group signed_identity_claims
+```
+
+Open http://127.0.0.1:8787 and sign in as **ada** with **august-demo**. `/me` returns the protected identity; `/docs` exposes endpoint contracts. The [gap ledger](web-library-gaps.md) distinguishes this verified development profile from broader provider, library and runtime support.

package/examples/approved-design/.aug-spec/august/0.19.0/io/contracts.aug

@@ -0,0 +1,36 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console:
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console:
+    write<T>(T value):
+        print(value=value)
+
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader:
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter:
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter:
+    read(string path) returns string unless FileError:
+        return read_file(path=path)
+    write(string path, string content) unless FileError:
+        write_file(path=path, content=content)
+
+/** Read command-line input through an explicit dependency. */
+capability Arguments:
+    read() returns List<string> uses Arguments.read
+
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments:
+    read() returns List<string>:
+        return arguments()