V1.0

.github/workflows/release.yml

@@ -0,0 +1,151 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: Build ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            archive: tar.gz
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+            archive: tar.gz
+            cross: true
+          - target: x86_64-apple-darwin
+            os: macos-latest
+            archive: tar.gz
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            archive: tar.gz
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+            archive: zip
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install cross-compilation tools
+        if: matrix.cross
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu
+          echo "CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc" >> $GITHUB_ENV
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.target }}
+
+      - name: Build release binary
+        run: cargo build --release --target ${{ matrix.target }}
+
+      - name: Determine version
+        id: version
+        shell: bash
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Package (unix)
+        if: matrix.archive == 'tar.gz'
+        shell: bash
+        run: |
+          STAGING="astra-${{ steps.version.outputs.version }}-${{ matrix.target }}"
+          mkdir -p "$STAGING"
+          cp "target/${{ matrix.target }}/release/astra" "$STAGING/"
+          cp README.md LICENSE* "$STAGING/" 2>/dev/null || true
+          tar czf "$STAGING.tar.gz" "$STAGING"
+          shasum -a 256 "$STAGING.tar.gz" > "$STAGING.tar.gz.sha256"
+          echo "ASSET=$STAGING.tar.gz" >> $GITHUB_ENV
+          echo "CHECKSUM=$STAGING.tar.gz.sha256" >> $GITHUB_ENV
+
+      - name: Package (windows)
+        if: matrix.archive == 'zip'
+        shell: bash
+        run: |
+          STAGING="astra-${{ steps.version.outputs.version }}-${{ matrix.target }}"
+          mkdir -p "$STAGING"
+          cp "target/${{ matrix.target }}/release/astra.exe" "$STAGING/"
+          cp README.md LICENSE* "$STAGING/" 2>/dev/null || true
+          7z a "$STAGING.zip" "$STAGING"
+          certutil -hashfile "$STAGING.zip" SHA256 > "$STAGING.zip.sha256"
+          echo "ASSET=$STAGING.zip" >> $GITHUB_ENV
+          echo "CHECKSUM=$STAGING.zip.sha256" >> $GITHUB_ENV
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: astra-${{ matrix.target }}
+          path: |
+            ${{ env.ASSET }}
+            ${{ env.CHECKSUM }}
+
+  release:
+    name: Create Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Determine version
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          cat > release_notes.md << 'NOTES'
+          ## Installation
+
+          **macOS / Linux:**
+          ```sh
+          curl -fsSL https://raw.githubusercontent.com/jaimeam/astra/main/install-binary.sh | sh
+          ```
+
+          **Or download a binary below** and add it to your `PATH`.
+
+          ### Checksums
+          Each archive has an accompanying `.sha256` file for integrity verification.
+
+          ### Targets
+          | Platform | File |
+          |----------|------|
+          | Linux x86_64 | `astra-VERSION-x86_64-unknown-linux-gnu.tar.gz` |
+          | Linux aarch64 | `astra-VERSION-aarch64-unknown-linux-gnu.tar.gz` |
+          | macOS x86_64 | `astra-VERSION-x86_64-apple-darwin.tar.gz` |
+          | macOS aarch64 (Apple Silicon) | `astra-VERSION-aarch64-apple-darwin.tar.gz` |
+          | Windows x86_64 | `astra-VERSION-x86_64-pc-windows-msvc.zip` |
+          NOTES
+          sed -i "s/VERSION/$VERSION/g" release_notes.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: Astra ${{ steps.version.outputs.version }}
+          body_path: release_notes.md
+          draft: false
+          prerelease: ${{ contains(steps.version.outputs.version, '-') }}
+          files: artifacts/*

CHANGELOG.md

@@ -1,46 +1,94 @@
 # Changelog
 
-## v1.0.0
+All notable changes to Astra will be documented in this file.
 
-Astra v1.0 — the first release ready for real projects.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-05
+
+Astra v1.0 — the first stable release, ready for real projects.
+See [docs/stability.md](docs/stability.md) for the stability guarantee.
 
 ### Language
 
-- Full syntax: modules, functions, let bindings, if/else, match, for/while loops, break/continue/return
+- Full syntax: modules, functions, let bindings, if/else, match, for/while loops,
+  break/continue/return
 - Type system with inference, generics, traits, type aliases, and invariants
-- Enums with associated data, Option[T], Result[T, E], and the `?` operator
+- Enums with associated data, Option[T], Result[T, E], and the `?` / `?else` operators
 - Capability-based effects system (Console, Fs, Net, Clock, Rand, Env) with user-defined effects
-- Pattern matching with exhaustiveness checking
+- Pattern matching with exhaustiveness checking and guard clauses
 - String interpolation (`"${expr}"`), multiline strings (`"""..."""`), escape sequences
 - Range expressions (`0..10`, `0..=10`)
 - Pipe operator (`value |> fn`)
-- Tail call optimization
-- Contracts (`requires`/`ensures`)
-- Mutable bindings (`let mut`)
+- Tail call optimization for self-recursive functions
+- Contracts (`requires`/`ensures`) and type invariants
+- Mutable bindings (`let mut`) with compound assignment (`+=`, `-=`, `*=`, `/=`, `%=`)
+- Closures and lambdas as first-class values
 
 ### Toolchain
 
 - `astra run` — execute programs with real Fs/Net/Clock/Rand capabilities
 - `astra check` — type check with JSON output, `--watch` mode, incremental caching
-- `astra test` — deterministic test runner with mock injection and property tests
-- `astra fmt` — canonical formatter
-- `astra fix` — auto-apply diagnostic suggestions
-- `astra explain` — detailed error code explanations (55 codes)
+- `astra test` — deterministic test runner with mock injection, `--filter`, `--seed`, `--watch`
+- `astra fmt` — canonical formatter (idempotent, deterministic)
+- `astra fix` — auto-apply diagnostic suggestions with `--dry-run`
+- `astra explain` — detailed error code explanations (57 codes)
 - `astra repl` — interactive REPL
 - `astra init` — project scaffolding with `--lib` support
-- `astra doc` — generate API docs from `##` comments
+- `astra doc` — generate API docs from `##` comments (markdown/html)
 - `astra lsp` — LSP server with diagnostics, hover, completion, and code actions
 
-### Standard Library (12 modules)
+### Standard Library (15 modules)
+
+- `std.core` — identity, constant, Unit type alias
+- `std.prelude` — auto-imported common utilities
+- `std.option` — Option handling: is_some, is_none, unwrap_or, map
+- `std.result` — Result handling: is_ok, is_err, unwrap_or, map, map_err
+- `std.error` — Error utilities: wrap, from_text, or_else
+- `std.list` — List utilities: is_empty, head, sort_by
+- `std.collections` — Advanced collections: group_by, frequencies, chunks
+- `std.iter` — Iterator functions: sum, product, all, any, reduce, flat_map
+- `std.string` — String utilities: is_blank, pad_left, pad_right, chars
+- `std.math` — Math functions: abs_val, min_val, max_val, clamp, is_even, is_odd
+- `std.io` — I/O wrappers with effect declarations
+- `std.json` — JSON parse and stringify
+- `std.regex` — Regular expression matching, replace, split
+- `std.datetime` — Date parsing, formatting, arithmetic, leap year detection
+- `std.path` — File path manipulation: basename, dirname, extension, join, normalize
+
+### Diagnostics (57 error codes)
+
+- E0xxx: Syntax/parsing errors (11 codes)
+- E1xxx: Type errors (16 codes)
+- E2xxx: Effect errors (7 codes)
+- E3xxx: Contract violations (5 codes)
+- E4xxx: Runtime errors (8 codes)
+- W0xxx: Warnings (8 codes)
+- Multi-error recovery: parser reports multiple errors per file
+- Stack traces with source locations (file:line:col)
+- Machine-actionable suggestions with auto-fix support
+- JSON output format for tool integration (`--json`)
+
+### Performance
+
+- Map/Set operations use O(log n) sorted binary search
+- Tail-call optimization for self-recursive functions
+- Incremental caching for `astra check`
+- See [docs/performance.md](docs/performance.md) for full details
+
+### Architecture Decisions
 
-`std.core`, `std.math`, `std.string`, `std.collections`, `std.list`, `std.option`, `std.result`, `std.prelude`, `std.json`, `std.io`, `std.iter`, `std.error`
+- ADR-001: Rust as implementation language
+- ADR-002: Explicit effects over monads
+- ADR-003: No null — Option[T] and Result[T, E] instead
+- ADR-004: Built-in linting in `astra check`
+- ADR-005: Interpreter-TypeChecker sync invariant
+- ADR-006: v1.0 release assessment
+- ADR-007: Async/await and package manager deferred to v1.1
 
-### Known Limitations
+### Not Included (Planned for v1.1)
 
-See [README.md](README.md#known-limitations-v10) for the full list. Key items:
-- No full Hindley-Milner type inference
-- Traits are runtime-dispatched
-- Single-threaded (no concurrency)
-- Interpreted only (tree-walking)
-- No package manager
-- No debugger
+- Async/await — syntax reserved, not yet functional
+- Package manager — `astra pkg` command exists, resolution not implemented
+- See [ADR-007](docs/adr/ADR-007-defer-async-pkg-to-v1.1.md) for rationale

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "astra"
-version = "0.1.1"
+version = "1.0.0"
 edition = "2021"
 description = "Astra programming language - an LLM/Agent-native language"
 license = "MIT OR Apache-2.0"

README.md

@@ -27,8 +27,8 @@ Plus the building blocks you'd expect:
 - **No null** - `Option[T]` with exhaustive matching; compiler catches missing cases
 - **Typed error handling** - `Result[T, E]` with `?` and `?else` for concise propagation
 - **Canonical formatting** - mandatory built-in formatter, no configuration
-- **JSON / regex / async** - built into the standard library
-- **Package management** - `astra pkg` for dependency management
+- **JSON / regex** - built into the standard library
+- **15 stdlib modules** - from `std.math` to `std.datetime` and `std.path`
 
 ```
 LLM generates code -> astra check -> JSON errors with fix suggestions -> LLM applies fixes -> repeat until passing
@@ -127,33 +127,11 @@ let cleaned = replace("\\s+", "  too   many   spaces  ", " ")
 let words = "hello world".split_pattern("\\s+")
 ```
 
-### Async/Await
+### Planned for v1.1
 
-Functions can be declared `async` and their results can be `await`ed. Calling an async function returns a `Future` value; `await` resolves it.
-
-```astra
-async fn fetch_data(url: Text) -> Text {
-  Net.get(url)
-}
-
-fn main() effects(Net) {
-  let data = await fetch_data("https://api.example.com/data")
-  println(data)
-}
-```
-
-### Package Management
-
-The `astra pkg` commands manage dependencies declared in `astra.toml`. Supports path, git, and registry dependencies with lockfile generation.
-
-```bash
-astra pkg add mylib --version "1.0"
-astra pkg add local-lib --path "../lib"
-astra pkg add remote-lib --git "https://github.com/example/lib"
-astra pkg install
-astra pkg list
-astra pkg remove mylib
-```
+- **Async/Await** — `async fn` and `await` syntax is reserved; full implementation coming in v1.1
+- **Package Manager** — `astra pkg` command exists; dependency resolution coming in v1.1
+- See [ADR-007](docs/adr/ADR-007-defer-async-pkg-to-v1.1.md) for rationale
 
 ## CLI Commands
 
@@ -169,22 +147,23 @@ astra pkg remove mylib
 | `astra init <name>` | Scaffold a new project |
 | `astra doc [files...]` | Generate API documentation |
 | `astra lsp` | Start LSP server |
-| `astra pkg install` | Install dependencies from astra.toml |
-| `astra pkg add <name>` | Add a dependency |
-| `astra pkg remove <name>` | Remove a dependency |
-| `astra pkg list` | List installed packages |
+| `astra pkg` | Package management (v1.1) |
 
 ## Documentation
 
-- **[Why Astra?](docs/why-astra.md)** - The case for an LLM-native language
-- [Getting Started](docs/getting-started.md) - Tutorial for your first Astra program
-- [Astra by Example](docs/examples.md) - Cookbook of common patterns and idioms
-- [Language Specification](docs/spec.md) - Complete syntax and semantics reference
-- [Effects System](docs/effects.md) - Guide to Astra's capability-based effects
-- [Testing Guide](docs/testing.md) - How to write and run tests
-- [Standard Library](docs/stdlib.md) - API reference for built-in types and functions
-- [Error Codes Reference](docs/errors.md) - All error codes with examples and fixes
-- [Formatting Rules](docs/formatting.md) - Canonical formatting specification
+- **[Why Astra?](docs/why-astra.md)** — The case for an LLM-native language
+- [Getting Started](docs/getting-started.md) — Tutorial for your first Astra program
+- [Astra by Example](docs/examples.md) — Cookbook of common patterns and idioms
+- [Language Specification](docs/spec.md) — Complete syntax and semantics reference
+- [Formal Grammar](docs/grammar.md) — EBNF grammar for the language
+- [Effects System](docs/effects.md) — Guide to Astra's capability-based effects
+- [Testing Guide](docs/testing.md) — How to write and run tests
+- [Standard Library](docs/stdlib.md) — API reference for built-in types and functions
+- [Error Codes Reference](docs/errors.md) — All error codes with examples and fixes
+- [Formatting Rules](docs/formatting.md) — Canonical formatting specification
+- [Performance](docs/performance.md) — Performance characteristics and guidance
+- [Stability Guarantee](docs/stability.md) — v1.0 stability promises
+- [Changelog](CHANGELOG.md) — Version history
 
 ## Project Structure
 
@@ -203,13 +182,15 @@ astra/
 └── examples/            # Example programs
 ```
 
-## Known Limitations
-
-- **Traits are runtime-dispatched** - Trait method calls are resolved at runtime, not compile time. The type checker validates trait impl blocks but does not resolve trait methods on arbitrary expressions. Incorrect trait usage is caught at runtime.
+## Known Limitations (v1.0)
 
-- **Interpreted only** - All execution is via a tree-walking interpreter. Performance is adequate for small and medium programs but not suitable for compute-heavy workloads. For performance-critical code, consider calling out to external tools via effects.
+- **Interpreted only** — Tree-walking interpreter. Adequate for scripts and tools, not for compute-heavy workloads. See [docs/performance.md](docs/performance.md).
+- **Traits are runtime-dispatched** — The type checker validates trait impl blocks, but trait method calls are resolved at runtime.
+- **No debugger** — Use `println`, `assert`/`assert_eq`, and `test` blocks for debugging.
+- **Async/await not yet functional** — Syntax is reserved for v1.1.
+- **Package manager not yet functional** — `astra pkg` exists but resolution is not implemented until v1.1.
 
-- **No debugger** - There is no step-through debugger. Use `println` for debugging output, `assert`/`assert_eq` for runtime checks, and `test` blocks for verifying behavior.
+See [docs/stability.md](docs/stability.md) for the v1.0 stability guarantee.
 
 ## Contributing