# A7 Full Docs Corpus

Generated from site/public/docs/*.md.

# A7 Documentation

Source: https://code5717.github.io/a7-py/docs/index.md

# A7 Documentation

A7 is an ahead-of-time compiler. It lowers `.a7` source to a single Zig 0.16
file, then the host Zig toolchain builds a native binary. The compiler is
Python. There is no A7 runtime.

## Pipeline

```text
.a7 → tokenize → parse → semantic checks → emit Zig → native binary
```

## Read order

| Need | Page |
| --- | --- |
| Install and run your first program | [Start](/a7-py/start/) |
| Syntax and language rules | [Language](/a7-py/language/) |
| Built-in modules | [Stdlib](/a7-py/stdlib/) |
| Compiler pipeline and CLI | [Compiler](/a7-py/compiler/) |
| Current gaps and priorities | [Status](/a7-py/status/) |
| Release gates and deploy | [Release](/a7-py/release/) |
| curl / agent fetch paths | [Agent Usage](/a7-py/agent-usage/) |
| Contributing and doc maintenance | [Project](/a7-py/project/) |

## Repository docs

The site compresses material from the repository. For compiler work, treat these
as authoritative:

- `README.md` — everyday usage and examples
- `docs/SPEC.md` — language semantics
- `docs/STATUS.md` — gaps and priorities
- `docs/RELEASE.md` — release gates

Drift between the site and repository docs is a bug.

## Public contract

These URLs are intentionally stable:

- `/a7-py/`
- `/a7-py/llms.txt`
- `/a7-py/llms-full.txt`
- `/a7-py/docs/index.md`
- `/a7-py/docs/start.md`
- `/a7-py/docs/language.md`
- `/a7-py/docs/stdlib.md`
- `/a7-py/docs/compiler.md`
- `/a7-py/docs/status.md`
- `/a7-py/docs/release.md`
- `/a7-py/docs/agent-usage.md`
- `/a7-py/docs/project.md`

# Start

Source: https://code5717.github.io/a7-py/docs/start.md

# Start

## Requirements

- Python 3.13 or newer
- `uv` for the Python environment
- Zig 0.16.0 to build generated Zig output
- Bun to build the docs site locally

## Install

```bash
git clone https://github.com/code5717/a7-py.git
cd a7-py
uv sync
zig version
```

The preferred compiler entry point is:

```bash
uv run a7 examples/001_hello.a7
```

The repository wrapper is equivalent:

```bash
uv run python main.py examples/001_hello.a7
```

## First compile

```bash
uv run a7 examples/001_hello.a7 --mode compile
zig run examples/001_hello.zig
```

The backend writes one Zig file per A7 input. Multi-file A7 input can be
resolved by the compiler, but the generated Zig output remains single-file.

## Language tour

Read the current language surface in one verified example file:

```bash
uv run a7 examples/037_language_tour.a7 --mode pipeline
```

See [Language](/a7-py/language/) for a short reference. Full semantics live in
`docs/SPEC.md`.

## Useful modes

| Mode | Purpose |
| --- | --- |
| `tokens` | Show lexer output |
| `ast` | Show parsed structure |
| `semantic` | Run semantic checks |
| `pipeline` | Run the full compiler pipeline without writing a file |
| `compile` | Emit Zig |
| `doc` | Emit compiler documentation output |

Use `--format json` for tools and agents. CLI modes and exit codes are listed on
the [Compiler](/a7-py/compiler/) page.

## Verify locally

Quick check after a compiler change:

```bash
uv run python scripts/verify_examples_e2e.py
```

Full release gate (heavier):

```bash
./run_all_tests.sh
```

Use the full gate before tagging or claiming a compiler change is complete. See
[Release](/a7-py/release/) for the complete checklist.

# Language

Source: https://code5717.github.io/a7-py/docs/language.md

# Language

This page is the short operational reference. Full semantics are in
`docs/SPEC.md`. Verified examples live under `examples/`, especially
`037_language_tour.a7`.

## Program shape

Top-level bindings and functions use `::`. Functions use `fn`, explicit
`ret`, and typed parameters.

```a7
io :: import "std/io"

greet :: fn(name: string) {
    io.println("Hello, {}!", name)
}

main :: fn() {
    greet("A7")
}
```

## Declarations

- Top-level constants and functions: `name :: value`
- Mutable locals with inference: `count := 0`
- Explicit type: `count: i32 = 0`

## Control flow

Use `if`, `while`, `for`, `break`, `continue`, and `match`. A7 source
recursion is rejected at compile time. Rewrite recursive algorithms with loops,
index worklists, or explicit stacks.

```a7
sum_to :: fn(n: usize) usize {
    total: usize = 0
    i: usize = 0
    while i <= n {
        total = total + i
        i = i + 1
    }
    ret total
}
```

Indexed iteration:

```a7
for index, value in items {
    // index is usize
}
```

## Types

Examples and docs may use:

- Integers and floats
- `bool`, `char`, strings
- Fixed arrays and slices
- Structs, enums, and untagged unions
- References with nil checks
- Simple generic functions and structs

Reserved or incomplete areas belong in [Status](/a7-py/status/), not in
examples that pretend they are complete.

## Imports

Standard library imports use virtual module paths:

```a7
io :: import "std/io"
math :: import "std/math"
```

Local file imports are being extended for multi-file programs. Generated Zig
remains single-file output.

## Hard rules

- A7 source recursion is rejected. Use loops, index worklists, or explicit
  stacks.
- Use `usize` for sizes, lengths, capacities, and indexes.
- Reserve `isize` for signed pointer-sized offsets and position differences.
- `new [N]T` is rejected. Use stack arrays or slices.
- Public reference syntax does not expose address-of or dereference operators.
  Pass lvalues directly to `ref` parameters.

# Standard Library

Source: https://code5717.github.io/a7-py/docs/stdlib.md

# Standard Library

A7 standard modules are virtual imports resolved by the compiler. No stdlib
source file is loaded from disk at compile time.

## Implemented modules

Only these modules are registered in the compiler today:

### `std/io`

Import path: `"std/io"`. Bindings: `print`, `println`, `eprintln`.

```a7
io :: import "std/io"

main :: fn() {
    io.println("hello")
    io.eprintln("stderr: {}", 42)
}
```

### `std/math`

Import path: `"std/math"`. Functions: `sqrt`, `abs`, `floor`, `ceil`, `sin`,
`cos`, `tan`, `log`, `exp`, `min`, `max`.

Typed variants such as `sqrt_f32` and `sqrt_f64` are also available as bare
builtins.

```a7
io :: import "std/io"
math :: import "std/math"

main :: fn() {
    x := math.sqrt(2.0)
    io.println("sqrt(2) = {}", x)
}
```

## Not registered yet

The repository contains stub modules for `mem` and `string`, but they are not
registered in the compiler. Do not use them in examples until they appear in
[Status](/a7-py/status/) as implemented.

These are planned but not available:

- `std/random` — deterministic, seed-driven APIs
- `std/debug` — debugging aids
- `Option<T>` and `Result<T, E>`
- Small collections such as `Vec`

File IO, network IO, and concurrency are out of scope for the current stdlib.

# Compiler

Source: https://code5717.github.io/a7-py/docs/compiler.md

# Compiler

The package lives under `a7/`. The CLI entry point is `a7.cli:main`, exposed as
`uv run a7` after `uv sync`.

## Pipeline

1. Tokenize source
2. Parse into AST
3. Resolve names and imports
4. Type check
5. Validate language invariants
6. Plan safety obligations
7. Preprocess AST for backend emission
8. Emit Zig
9. Let Zig build the native binary

Failures in tokenization, parsing, semantic validation, code generation, and
internal errors have stable exit stages for tool usage.

## CLI modes

| Mode | Purpose |
| --- | --- |
| `compile` | Emit Zig (default) |
| `tokens` | Show lexer output |
| `ast` | Show parsed structure |
| `semantic` | Run semantic checks |
| `pipeline` | Full pipeline without writing a file |
| `doc` | Emit compiler documentation output |

Add `--format json` for machine-readable output.

## Exit codes

| Code | Stage |
| --- | --- |
| 0 | Success |
| 2 | Usage error |
| 3 | I/O error |
| 4 | Tokenize error |
| 5 | Parse error |
| 6 | Semantic error |
| 7 | Codegen error |
| 8 | Internal error |

## Safety stance

A7 rejects direct recursion, mutual recursion, and local function-pointer
alias-cycle recursion. Compiler internals also avoid recursive AST traversal.

The safety layer focuses on compile-time checks for:

- narrowing casts
- division and modulo denominator checks
- indexing and slicing bounds
- nil reference use
- direct use after `del`

These checks are compiler guarantees, not an OS sandbox.

## Zig backend

The Zig backend targets Zig 0.16.0. Generated Zig should be readable, preserve
source structure where practical, and remain single-file even when A7 imports
multiple input files.

Debug and release artifact builders verify generated source and binaries. See
[Release](/a7-py/release/) for artifact gate commands.

# Status

Source: https://code5717.github.io/a7-py/docs/status.md

# Status

A7 is pre-1.0. The compiler is usable for the checked example suite, but the
language and stdlib are still intentionally small. The authoritative status
document is `docs/STATUS.md`.

## Current surface

- Zig is the only supported public backend
- Source recursion is rejected at compile time
- The example suite is verified against golden output fixtures
- Static docs site with raw markdown and agent corpus files

## Active priorities

- Multi-file A7 source support with single-file Zig output
- Generic specialization before broad cross-module generic workflows
- Clearer status reporting for parsed-only language features
- Practical stdlib additions starting with deterministic random helpers

## Known gaps

- File-backed imports, `using import`, and broad cross-module type checking
  remain follow-up work
- Fixed-width overflow, union discriminant access, and full ref/del alias
  behavior are incomplete
- Multiple return value destructuring, tagged union tag workflows, and
  variadic runtime lowering are not current backend features
- `Option`, `Result`, collections, and fuller string/memory helpers are
  planned stdlib work

## Deferred

- Package registry
- File and network IO in the stdlib
- Concurrency primitives
- Full language server
- Runtime sandboxing

If a feature is listed here as deferred, do not write public examples that rely
on it as if it is complete.

For release gates and deploy checks, see [Release](/a7-py/release/).

# Release

Source: https://code5717.github.io/a7-py/docs/release.md

# Release

The canonical release checklist is `docs/RELEASE.md`. This page is the public
summary.

## Local gates

```bash
uv run python scripts/verify_examples_e2e.py
uv run python scripts/build_examples.py --profile debug --backend zig --clean
uv run python scripts/build_examples.py --profile release --backend zig --clean
cd site && bun install && bun run build
./run_all_tests.sh
```

`run_all_tests.sh` is the single local release gate. It covers pytest, example
E2E, debug and release artifacts, error-stage matrix, docs style, secrets check,
package build, and wheel install smoke test.

## Docs gate

The docs workflow runs:

```bash
python3 scripts/check_docs_style.py
cd site
bun install --frozen-lockfile
bun run lint
bun run build
```

The build writes `site/dist`, then GitHub Pages publishes that directory.

## Required archive files

The release workflow verifies that the docs archive contains:

- `dist/llms.txt`
- `dist/llms-full.txt`
- `dist/docs/index.md`
- `dist/docs/agent-usage.md`
- `dist/docs/release.md`
- `dist/docs/status.md`

Keep these paths stable unless the release workflow changes in the same commit.

## Native artifacts

Release archives include Zig source and binaries for the example suite. Archive
names include the target toolchain: `zig0.16.0`.

For contributing and doc maintenance rules, see [Project](/a7-py/project/).

# Agent Usage

Source: https://code5717.github.io/a7-py/docs/agent-usage.md

# Agent Usage

Prefer raw text URLs over crawling the visual site. Every rendered page has a
markdown twin under `/a7-py/docs/<slug>.md`.

## Fetch order

```bash
curl -fsSL https://code5717.github.io/a7-py/llms.txt
curl -fsSL https://code5717.github.io/a7-py/llms-full.txt
curl -fsSL https://code5717.github.io/a7-py/docs/language.md
```

## Compact index

`llms.txt` lists every public markdown page with a short summary. Use it first
when choosing which page to fetch.

## Full corpus

`llms-full.txt` concatenates the whole public docs corpus. Use it when one
fetch with the entire public context is enough.

## Agent rules

- Treat `README.md`, `docs/SPEC.md`, `docs/STATUS.md`, and `docs/RELEASE.md`
  as authoritative when changing the compiler.
- Treat site markdown as public-facing compression of those sources.
- Keep generated Zig output single-file.
- Do not author A7 examples that rely on source recursion.

## Deploy verification

After a docs deploy:

```bash
curl -fsSI https://code5717.github.io/a7-py/
curl -fsSL https://code5717.github.io/a7-py/docs/index.md
curl -fsSL https://code5717.github.io/a7-py/llms.txt
```

See [Project](/a7-py/project/) for contribution and doc maintenance rules.

# Project

Source: https://code5717.github.io/a7-py/docs/project.md

# Project

## Contributing

Before changing language behavior, read:

- `docs/SPEC.md`
- `docs/STATUS.md`
- `docs/SAFETY_CONTRACT.md`
- `docs/RELEASE.md`

Small changes should still update public docs when they affect user-visible
behavior.

## Documentation maintenance

Keep the docs minimal:

- Long history belongs in `git log`, not the website.
- Current gaps belong in [Status](/a7-py/status/).
- Release-facing notes belong in `docs/CHANGELOG.md`.
- Public site pages should summarize, not duplicate every internal document.

When language features or user-visible behavior change, update `docs/CHANGELOG.md`,
`README.md`, `docs/SPEC.md`, and `docs/STATUS.md` as needed. Keep the site
corpus in `site/public/docs/` aligned with those sources.

Agent fetch paths and curl workflows live on [Agent Usage](/a7-py/agent-usage/).

## Deploy

The `Deploy Docs` GitHub Actions workflow publishes `site/dist` to GitHub
Pages. The published base path is `/a7-py/`.

Release gates and required archive paths are on [Release](/a7-py/release/).

## Security

`a7-py` is not a sandbox. The compiler emits Zig and the host toolchain builds
native code. Only compile and execute source you trust.