@greenpandastudios/aug-cli 0.19.0

package/docs/benchmarks.json

@@ -0,0 +1,38 @@
+{
+  "recordedAt": "2026-09-28T16:48:45.210Z",
+  "version": "0.15.0",
+  "workload": "examples/benchmark/main.aug",
+  "entries": 20000,
+  "expectedOutput": "599970000\ntrue\n",
+  "environment": {
+    "platform": "darwin",
+    "release": "25.6.0",
+    "architecture": "arm64",
+    "cpu": "Apple M5",
+    "node": "v24.18.0"
+  },
+  "optimization": "release (-O2)",
+  "iterations": 10,
+  "warmup": 2,
+  "includesProcessStartup": true,
+  "units": "milliseconds",
+  "samples": [
+    6.0544590000000085,
+    6.099375000000009,
+    5.33745799999997,
+    4.996000000000038,
+    4.762875000000008,
+    4.77962500000001,
+    4.676667000000009,
+    4.5241249999999695,
+    4.297333000000037,
+    4.267916999999954
+  ],
+  "median": 4.77962500000001,
+  "p95": 6.099375000000009,
+  "minimum": 4.267916999999954,
+  "compiler": {
+    "executable": "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang",
+    "version": "Apple clang 21.0.0 (clang-2100.3.34.2)"
+  }
+}

package/docs/compatibility.md

@@ -0,0 +1,42 @@
+# Compatibility and supported platforms
+
+August 0.19 is a preview. This page states the proposed 1.0 compatibility contract and the evidence still needed before it takes effect. The [roadmap](roadmap.md) tracks that release gate.
+
+The [ownership and task conformance page](language-conformance.md) records executable candidate behavior for moves, aliasing, cleanup, cancellation, and delayed errors.
+
+## What a 1.0 release will keep stable
+
+| Surface | 1.x promise |
+| --- | --- |
+| August source | Accepted syntax, import visibility, labeled calls, types, ownership, effects, checked errors, tasks, and same-file tests keep their documented meaning through 1.x. Minor releases can add syntax or APIs. |
+| CLI and project files | Documented `aug` commands, `main.yaml` keys, `aug-package.json`, and `aug.lock.json` retain compatible reading within 1.x. New fields have defaults; removing or changing a field requires a major release. |
+| First-party packages | CLI, standard, web, and crypto packages use one exact version. A release tests installed tarballs together; mixing versions is unsupported. User packages declare a compatible compiler range and retain their own public `export.aug` surface. |
+| Generated specifications | `aug spec` remains deterministic for a given compiler and project. Text and layout can improve between versions; tools should link to source and declarations rather than parse Markdown prose. |
+| Native boundary | `extern C` uses documented C-width mappings and the target platform's C ABI. The generated C runtime and `AugValue` layout are compiler-private today. Before 1.0, the project must either publish and test a versioned adapter ABI or keep that runtime surface private and verify that public `extern C` adapters need no private structure. |
+
+A change that makes valid 1.x source fail to compile, changes its observable behavior, or removes a documented public name is breaking. A safety or correctness repair may require a narrow exception, but its release must explain the affected code, provide a diagnostic, and provide `aug migrate` support when mechanical migration is possible. Security fixes can be released promptly; they still get a compatibility note.
+
+## Migration between versions
+
+Each release documents source, configuration, package, and native changes in the changelog. When spelling can be changed safely, `aug migrate PROJECT` performs or suggests the edit. For changes requiring a choice, the diagnostic explains the alternatives without rewriting behavior silently. Upgrade the four first-party packages and the extension together, then run:
+
+```sh
+aug check PROJECT
+aug test PROJECT
+aug spec PROJECT --check
+```
+
+Rebuild native executables and private dependencies for the target platform after a compiler upgrade. `aug.lock.json` and the pinned native dependency manifest provide the input versions; a compiled executable is not promised to work with a different runtime image or native dependency set.
+
+## Platform evidence
+
+| Target | Preview evidence | 1.0 support decision |
+| --- | --- | --- |
+| macOS ARM64 | Local pinned native bootstrap and full suite pass. | Candidate; require repeated CI and packaged CLI tests. |
+| Linux ARM64 | Local Docker full native suite passes; core, crypto, and typed HTTP programs run in the matching runtime image. | Candidate; require repeated CI and package tests. |
+| Linux x86-64 | Docker CI is configured for the same full native suite and runtime smoke programs. | Candidate only after that CI gate passes. |
+| Windows and other targets | No full native verification. | Outside the proposed 1.0 support matrix. |
+
+Node.js 24+, a C11 compiler, and the [native prerequisites](tooling.md) are required for source builds. The Docker recipes provide those build tools on Linux. The current runtime schedules tasks on one OS thread. HTTP and OIDC library conformance is tracked separately in the [web and crypto gap ledger](web-library-gaps.md); those application concerns are not language 1.0 gates.
+
+The 1.0 support matrix becomes a commitment only after each candidate target has green CI, installed-package and native integration tests, dependency/license review, and a documented update path. See [production readiness](production-readiness.md) for present limits.

package/docs/concurrency-implementation.md

@@ -0,0 +1,18 @@
+# Structured execution implementation
+
+This is an implementation work note, not a delivery claim.
+
+The confirmed model uses lexical scopes, ordered waits, cooperative cancellation, guaranteed cleanup, shared read references, exclusive mutation, bounded multicore workers and nonblocking I/O. An unhandled child failure cancels its siblings; a request failure leaves other requests running.
+
+The same-app OIDC flow requires an outbound request to suspend its execution while the native HTTP event loop continues accepting provider requests. Running that request synchronously inside an HTTP callback would deadlock.
+
+Implementation seams:
+
+- Each execution owns its root-frame chain, error state and scope stack. The collector traces all suspended executions and native retained roots.
+- Scoped DI caches belong to scope instances. Shared bindings remain process values; fresh bindings remain uncached.
+- Managed request values cross the transport seam through retained GC roots. Native buffers have explicit transport ownership.
+- A task captures read references and moves owned arguments. Mutable argument loans stay active until join. Collection waits preserve input order.
+- Native I/O starts on the event loop and resumes a suspended execution on completion or cancellation. No worker waits on a blocking socket.
+- Multicore execution requires collector safepoints and synchronization of explicit Shared values. A single event loop alone must not be presented as the completed multicore requirement.
+
+Verification must include two requests in the same process that call each other, bounded fan-out, sibling cancellation, cleanup on errors and disconnects, lock restrictions and mutation alias rejection.

package/docs/diagnostics.md

@@ -0,0 +1,97 @@
+# AugScript diagnostics and fixes
+
+Diagnostics include a code, source location, and expected/actual contract where relevant. VS Code shows them while editing, with hover guidance and lightbulb actions. Fixes are precise edits; they are offered only where the compiler has enough information. Warnings do not prevent a build.
+
+## Syntax and data
+
+| Code | Meaning and remedy |
+| --- | --- |
+| LEX | Check quotes, escapes, comments, Unicode, and token spelling. Strings cannot contain NUL or invalid Unicode. |
+| PARSE | Check delimiters and Type name order. Declarations omit class/function; error clauses use unless. Migration fixes remove the old keywords. A constructor body needs implements after it. |
+| INDENT | A colon needs a newline and indented body. Keep prefixes consistent; align dedents with an open block. Use pass for an empty body. |
+| NUMBER | int literals must fit signed 64 bits, including the exact negative minimum. Float literals must be finite. |
+| TYPE | Check the expected type, nullable status, generic arguments, and input/return contract. User generics are invariant unless an interface declares checked variance. |
+| CALL | Supply ordinary labels exactly once; resolve inputs are omitted from a call. Inference must be concrete and consistent. |
+| COLLECTION | Empty literals need context. List/Set elements and Map keys/values must fit. Tuple indexes are compile-time constants. |
+| RECORD | Data fields must be deeply immutable. Records cannot retain mutable collections, DI inputs, or ownership; validation cannot replace fields. |
+| MATCH | Cover null/bool cases and add else for open type domains. Remove duplicate, incompatible, or unreachable cases. |
+| PATTERN | Tuple destructuring needs matching arity and new names in the current scope. |
+| ITERATION | Iterate List, Set, Map, or a homogeneous Tuple; destructure heterogeneous tuples explicitly. |
+| MUTABILITY | Mark class storage mutable for later writes; a function receives borrow/own access rather than a mutable storage modifier. |
+
+Both braces and indentation are accepted. The formatter uses main.yaml preferences and checks that its output parses to the same program before returning an edit.
+
+## Modules and interfaces
+
+| Code | Meaning and remedy |
+| --- | --- |
+| PROJECT / MAIN | Supply main.aug at the root. Keep declarations in other files and imports/bindings before startup. |
+| SYNTAX | Use word booleans, initialize blocks, implement/with, and resolve/to. Preview `aug migrate PROJECT`, then use --write or the editor's verified migration fix. |
+| IMPORT / EXPORT | Import each file's dependencies. Cross-folder access needs export.aug; only exports belong in that file. Wildcards import visible local declarations, never internal imports. |
+| NAME | Correct spelling or import a visible declaration. Quick Fix offers an import when a unique accessible source exists. |
+| PRIVATE | A leading _ confines a declaration/member/module to its scope. Private names cannot be imported or exported. Constructor labels can differ from private storage. |
+| INTERFACE | Classes need implements and matching method types, labels, ownership, errors, and effects. Override conflicting defaults. Records are the immutable-data alternative. |
+| MODULE | An import cycle or forbidden folder dependency violates the module contract. The message includes the cycle or allowed dependencies. |
+| LINT | An optional architectural warning: wildcard imports, public helper growth, dependency fan-out, broad errors, discarded errors, or explicit shared state. |
+
+**Expand to named imports** is available for wildcard imports even without a diagnostic. Configure warnings and strict sibling boundaries in [main.yaml](tooling.md#configuration).
+
+## State, dependencies, and errors
+
+### EFFECT
+
+Callables are pure by default. Declare `changes self` for state transitions or `changes input` for an owned/borrowed input. Receive I/O capabilities through resolve headers and declare `uses dependency.operation`. Callers and interface contracts include every effective effect, including layers.
+
+Public fields and managed inputs grant reading. Mark local storage mutable when it needs initialization-independent changes. Constructors are pure; move startup effects into a named method. drop performs only local cleanup and cannot acquire effects/errors through interceptors.
+
+### DI
+
+Bindings belong in main, imported compositions, or test setup. Targets have only resolve header inputs and satisfy their key. The compiler rejects missing edges, duplicate keys, cycles, unsafe scoped retention, and effectful bound construction.
+
+Stateful objects default to fresh. Shared state requires `shared mutable`; scoped state requires `scoped mutable`. Resolve scoped dependencies inside scope; keep their references there.
+
+A helper's dependency belongs in its callable/class header. **Lift into the dependency header** replaces a precise body resolve and adds its typed resolve parameter. The application's missing binding remains a separate build error. Calls forward one compatible header dependency.
+
+### OWN / BORROW
+
+An own value moves into an own input/field/return. Do not copy it into managed storage or use it after a move. A mutable borrow is exclusive and cannot escape into a return or storage. Deep read-only values cannot be borrowed to bypass their contract.
+
+Alias tracking includes nested references, call arguments/results, DI identities, branches, and loop re-entry. An exclusive argument cannot overlap another argument or receiver. Quick Fix can wrap a standalone managed mutation in a borrow block when its local access is otherwise legal.
+
+### CONCURRENCY
+
+A child task keeps its captured objects available until `wait for` or its scope join. Wait before changing a captured object through a collection method, a borrowed call, or a field assignment. An already-open `borrow` block does not let the parent mutate while the child uses the object. See the [conformance rules](language-conformance.md).
+
+### THROWS
+
+A checked error lacks a compatible catch or unless declaration. The language uses `unless`; THROWS is the diagnostic identifier retained for tooling.
+
+**Propagate with unless** adds the specific error to the enclosing contract. At composition statements, **Catch and report the failure** creates a visible recovery template. Choose domain recovery deliberately; no fix silently discards an error.
+
+Errors must implement Error. List.get can raise IndexError, dynamic division ArithmeticError, file operations FileError, and c_int conversion ConversionError. Annotated callable errors include every layer's unless clause. Bound constructors must handle their layer errors internally.
+
+## Interceptors
+
+### INTERCEPTOR
+
+Declare an interceptor with one implemented around method. Constructor dependencies are managed resolve parameters; generic parameters belong on the interceptor. Apply a tag to an executable callable or constructor.
+
+Selected labels match automatically. `[Name(y=x)]` maps target x to around y. Every selected input has a compatible source, and mappings are unique. Ownership, outputs, effects, and errors must fit the target and any implemented interface. Layer dependencies also appear in the target's dependency header.
+
+Fixes can import a visible interceptor, inject a constructor dependency, add around to a braced declaration, or migrate an obsolete process entry point.
+
+### NEXT
+
+Next exists only inside around. `next()` forwards original inputs; `next(y=value)` replaces a mapped input. It cannot be stored, given generic arguments, or called from a helper. Each execution path calls it at most once; retries through loops/catches are rejected.
+
+## Tests, configuration, and native C
+
+| Code | Meaning and remedy |
+| --- | --- |
+| TEST | Put a class/function suite beside its declaration. Unique groups/cases; bindings before setup before cases. Check row arity/types and execute a bool assertion in each case. |
+| DOC | @param labels, value-return tags, and error tags must match the effective signature. Unknown tags are errors. Missing public docs become warnings only when enabled. |
+| CONFIG | main.yaml uses the supported keys and simple YAML lists. Unknown/duplicate keys and invalid values fail during check. |
+| FFI | Use supported boundary types, matching C widths, labeled inputs, unsafe, and uses C.function in callable contracts. |
+| NATIVE | A C compiler error mapped to its .aug file and line. Fix the boundary declaration or linker configuration; inspect emit-c for generated details. |
+
+See [testing](testing.md) and [native tooling](tooling.md) for executable examples and exact limits.

package/docs/docker.md

@@ -0,0 +1,35 @@
+# Docker build and run images
+
+The repository supplies two base images. The **build** image contains Node.js 24, the August compiler, Clang and its sanitizer runtime, and the pinned native task, JSON, web, and crypto dependencies. The **run** image is a small Debian userland with the matching native shared libraries and CA certificates. It runs a compiled August executable as an unprivileged user. Build the run image after the build image so both use the same native dependency build.
+
+Build the images from the repository root:
+
+```sh
+docker build -f docker/Dockerfile.build -t augscript/build:local .
+docker build -f docker/Dockerfile.run -t augscript/run:local .
+docker build -f docker/Dockerfile.crypto-smoke -t augscript/crypto-smoke:local .
+docker run --rm augscript/crypto-smoke:local
+docker build -f docker/Dockerfile.web-smoke -t augscript/web-smoke:local .
+docker run --rm -p 127.0.0.1:8080:8080 augscript/web-smoke:local
+```
+
+Create a project with `aug init my-app`, then compile it for Linux. The mount is writable because `aug build` writes `.aug-build` and generated specifications into the project. The following commands assume your Docker engine can bind-mount your working directory:
+
+```sh
+docker run --rm \
+  --user "$(id -u):$(id -g)" \
+  --mount type=bind,source="$PWD/my-app",target=/workspace \
+  augscript/build:local build . --out /workspace/.aug-build/program
+```
+
+Run that exact executable in the run image:
+
+```sh
+docker run --rm \
+  --mount type=bind,source="$PWD/my-app/.aug-build",target=/app,readonly \
+  augscript/run:local
+```
+
+The crypto smoke command prints the SHA-256 digest of `abc`. The web smoke image serves `GET /health` on port 8080 and returns `{"status":"ok"}`. The run image uses Debian bookworm's C runtime; a binary built with this build image uses the matching base distribution. The run image has no shell command in its entry point and contains no compiler, source, package manager, or application secrets. Supply environment, network, ports, and data mounts for your application when needed. These images are source recipes, not published registry tags.
+
+For a reproducible image build without a host bind mount, use a multistage Dockerfile: start with `FROM augscript/build:local AS build`, copy the application into `/workspace`, run `aug build /workspace --out /tmp/program`, then start with `FROM augscript/run:local` and copy `/tmp/program` to `/app/program` with `--chown=august:august`. The repository's [`Dockerfile.smoke`](../docker/Dockerfile.smoke) exercises this pattern with the generated starter.

package/docs/example-projects.json

@@ -0,0 +1,26 @@
+[
+  {"path":"examples/hello","title":"Hello world with dependencies","group":"Start here","description":"A greeter, a logger, narrow folder exports, and explicit application bindings."},
+  {"path":"examples/new-syntax","title":"Labeled calls and injection","group":"Start here","description":"Constructor injection, named inputs, ordinary functions, and same-file tests."},
+  {"path":"examples/developer-workflow","title":"A small tested application","group":"Start here","description":"A calculator module with logging, fixtures, groups, and parameterized tests."},
+  {"path":"examples/cli-args","title":"Command-line arguments","group":"Start here","description":"Read arguments, inspect collections, and return a process exit status."},
+  {"path":"examples/collections","title":"Lists, tuples, sets, and maps","group":"Values and errors","description":"Create typed collections and update them through checked mutable access."},
+  {"path":"examples/generics","title":"Generic contracts","group":"Values and errors","description":"Write reusable records, interfaces, classes, and functions with type parameters."},
+  {"path":"examples/generic-di","title":"Generic dependency injection","group":"Values and errors","description":"Bind a generic interface and resolve a class that uses it."},
+  {"path":"examples/errors","title":"Checked failures","group":"Values and errors","description":"Declare errors with unless, catch them, and run cleanup."},
+  {"path":"examples/ownership","title":"Read access and mutable borrows","group":"State and lifetime","description":"Share a reference for reading and grant explicit access for mutation."},
+  {"path":"examples/ownership-transfer","title":"Move ownership","group":"State and lifetime","description":"Transfer an owned resource between labeled calls."},
+  {"path":"examples/drop","title":"Resource cleanup","group":"State and lifetime","description":"Release an owned resource when its lifetime ends."},
+  {"path":"examples/visibility","title":"Private state and helpers","group":"State and lifetime","description":"Keep underscore-prefixed implementation details inside their scope."},
+  {"path":"examples/approved-design","title":"Modules and composition","group":"Modules and packages","description":"Combine domain modules, generic values, explicit capabilities, and scoped providers."},
+  {"path":"examples/interceptors","title":"Function and constructor middleware","group":"Modules and packages","description":"Layer interceptors, map inputs, and keep logging dependencies explicit."},
+  {"path":"examples/packages/math","title":"Create a package","group":"Modules and packages","description":"Publish a small arithmetic library through export.aug and test its public surface."},
+  {"path":"examples/packages/app","title":"Use a package","group":"Modules and packages","description":"Install the neighboring arithmetic package and import it through a local alias."},
+  {"path":"examples/ffi","title":"A native C boundary","group":"Native applications","description":"Declare a C operation and call it inside an unsafe block."},
+  {"path":"examples/benchmark","title":"A finite benchmark","group":"Native applications","description":"Measure a deterministic arithmetic workload with aug bench."},
+  {"path":"examples/oidc-login","title":"OpenID Connect login application","group":"Web applications","description":"A login page, provider, client, session JWT, and logout flow in one August project."},
+  {"path":"benchmarks/startup","title":"Startup benchmark","group":"Measured programs","description":"The small program used to measure process startup."},
+  {"path":"benchmarks/cpu","title":"CPU benchmark","group":"Measured programs","description":"Two million dependent integer steps with a checked result."},
+  {"path":"benchmarks/collections","title":"Map and Set benchmark","group":"Measured programs","description":"Insert, find, and iterate over 20,000 collection entries."},
+  {"path":"benchmarks/json","title":"JSON benchmark","group":"Measured programs","description":"Parse, decode, and serialize a typed record 5,000 times."},
+  {"path":"benchmarks/http","title":"HTTP benchmark","group":"Measured programs","description":"Serve the typed JSON endpoint used in the throughput measurements."}
+]

package/docs/examples/approved-design/counters.md

@@ -0,0 +1,253 @@
+---
+title: "counters.aug · Modules and composition"
+generated: true
+source: "examples/approved-design/counters.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `counters.aug`
+
+[Modules and composition](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`counters.aug`](counters.md)
+- [`domain/app.aug`](domain/app.md)
+- [`domain/export.aug`](domain/export.md)
+- [`domain/models.aug`](domain/models.md)
+- [`domain/numbers.aug`](domain/numbers.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+/** Reading state has no mutation effect. */
+interface State:
+    read() returns int
+_Initial() implements State:
+    read() returns int:
+        return 0
+_Updated(int count) implements State:
+    read() returns int:
+        return count
+/** A mutable counter with an explicit transition contract. */
+interface Counter:
+    increment() changes self
+    value() returns int
+_Counter(resolve mutable State initial to _state) implements Counter:
+    increment() changes self:
+        _state to _Updated(count=_state.read() + 1)
+    value() returns int:
+        return _state.read()
+/** The complete counter composition; its mutable state belongs to each scope. */
+composition Counters:
+    implement State with _Initial
+    implement Counter with _Counter scoped mutable
+```
+
+```aug [Braces]
+/** Reading state has no mutation effect. */
+interface State {
+    read() returns int
+}
+_Initial() implements State {
+    read() returns int {
+        return 0
+    }
+}
+_Updated(int count) implements State {
+    read() returns int {
+        return count
+    }
+}
+/** A mutable counter with an explicit transition contract. */
+interface Counter {
+    increment() changes self
+    value() returns int
+}
+_Counter(resolve mutable State initial to _state) implements Counter {
+    increment() changes self {
+        _state to _Updated(count=_state.read() + 1)
+    }
+    value() returns int {
+        return _state.read()
+    }
+}
+/** The complete counter composition; its mutable state belongs to each scope. */
+composition Counters {
+    implement State with _Initial
+    implement Counter with _Counter scoped mutable
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- [`State`](counters.md#symbol-State) is an interface.
+- [`_Initial`](counters.md#symbol-_Initial) is a class implementing `State`.
+- [`_Updated`](counters.md#symbol-_Updated) is a class implementing `State`.
+- [`Counter`](counters.md#symbol-Counter) is an interface.
+- [`_Counter`](counters.md#symbol-_Counter) is a class implementing `Counter`.
+- [`Counters`](counters.md#symbol-Counters) declares 2 providers.
+
+### `State` {#symbol-State}
+
+[source](counters.md#code)
+
+Interface.
+
+**Author documentation**
+
+Reading state has no mutation effect.
+
+#### `State.read` {#symbol-State.read}
+
+[source](counters.md#code)
+
+Returns: `int`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+### `Counter` {#symbol-Counter}
+
+[source](counters.md#code)
+
+Interface.
+
+**Author documentation**
+
+A mutable counter with an explicit transition contract.
+
+#### `Counter.increment` {#symbol-Counter.increment}
+
+[source](counters.md#code)
+
+Returns: no value.
+
+May change: `self`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+#### `Counter.value` {#symbol-Counter.value}
+
+[source](counters.md#code)
+
+Returns: `int`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+### `Counters` {#symbol-Counters}
+
+[source](counters.md#code)
+
+**Author documentation**
+
+The complete counter composition; its mutable state belongs to each scope.
+
+This composition declares these providers before startup:
+
+- Provide [`_Initial`](counters.md#symbol-_Initial) when `State` is requested. Reuse one instance.
+- Provide [`_Counter`](counters.md#symbol-_Counter) when `Counter` is requested. Reuse one instance per explicit scope. Permit explicit shared mutation. Required dependencies: `State`.
+
+### `_Initial` {#symbol-_Initial}
+
+[source](counters.md#code)
+
+Behavioral class, private to this file.
+
+Satisfies [`State`](counters.md#symbol-State).
+
+#### `_Initial.read` {#symbol-_Initial.read}
+
+[source](counters.md#code)
+
+Returns: `int`.
+
+**What it does**
+
+- Return `0`.
+
+### `_Updated` {#symbol-_Updated}
+
+[source](counters.md#code)
+
+Behavioral class, private to this file.
+
+Satisfies [`State`](counters.md#symbol-State).
+
+**Inputs**
+
+- `count` (`int`) — required labeled input — stored as `count` and read-only after initialization.
+
+#### `_Updated.read` {#symbol-_Updated.read}
+
+[source](counters.md#code)
+
+Returns: `int`.
+
+**What it does**
+
+- Return `count`.
+
+### `_Counter` {#symbol-_Counter}
+
+[source](counters.md#code)
+
+Behavioral class, private to this file.
+
+Satisfies [`Counter`](counters.md#symbol-Counter).
+
+**Inputs**
+
+- `initial` ([`State`](counters.md#symbol-State)) — injected; callers omit it — stored as `_state` (private) and mutable.
+
+#### `_Counter.increment` {#symbol-_Counter.increment}
+
+[source](counters.md#code)
+
+Returns: no value.
+
+May change: `self`.
+
+**What it does**
+
+- Set `_state` to call [`_Updated`](counters.md#symbol-_Updated) with `count` = (call [`State.read`](counters.md#symbol-State.read) on `_state` plus `1`).
+
+#### `_Counter.value` {#symbol-_Counter.value}
+
+[source](counters.md#code)
+
+Returns: `int`.
+
+**What it does**
+
+- Return call [`State.read`](counters.md#symbol-State.read) on `_state`.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::