// SPDX-License-Identifier: CC-BY-SA-4.0
= A2ML v1.0.0 Release Notes
:toc:
:toclevels: 2
:icons: font

== Overview

A2ML v1.0.0 is the first stable release of the Attested Markup Language, featuring a formally verified Idris2 core, complete tooling suite, and comprehensive documentation.

**Release Date:** 2026-01-30

== Highlights

=== Formally Verified Core

- **Idris2 implementation** with dependent types
- **4 proven theorems**: Uniqueness, reference resolution, validation, attestation
- **Total functions**: No partial functions, guaranteed termination
- **Type-safe parsing**: Compile-time guarantees

See: src/A2ML/Proofs.idr, docs/IDRIS2-CORE.adoc

=== Complete Tooling Suite

- **CLI** (`a2ml`): 5 commands (validate, check, format, convert, stats)
- **REPL** (`a2ml-repl`): Interactive development with 12 commands
- **LSP server** (architecture): Editor integration (VS Code, Neovim, Emacs)
- **Format converters**: Markdown, HTML, Djot, LaTeX, PlainText

See: docs/TOOLING.adoc

=== Self-Documentation (Dogfooding)

A2ML documents itself using A2ML:

- README.a2ml
- SPEC.a2ml
- docs/IANA-MEDIA-TYPE.a2ml

CI validates all .a2ml files and generates HTML/Markdown/LaTeX outputs.

=== Performance

- **Small docs** (<1KB): <50ms
- **Medium docs** (~10KB): <200ms
- **Large docs** (~100KB): <1s
- **RFC-sized** (~1.8MB): <15s

Target: 2-3x CommonMark speed with full validation.

See: docs/PERFORMANCE.adoc

== What's New in v1.0.0

=== Core Features

- [x] Surface grammar (EBNF specification)
- [x] Typed core (Idris2 with dependent types)
- [x] Progressive strictness (lax → checked → attested)
- [x] Unique ID validation
- [x] Reference resolution
- [x] Opaque payload preservation
- [x] 29 comprehensive tests

=== Directives

- `@abstract:` - Document abstract
- `@refs:` - References/bibliography
- `@fig:` - Figures with captions
- `@table:` - Tables with captions
- `@opaque:` - Byte-for-byte preservation

=== CLI Commands

- `a2ml validate <file>` - Full validation with proofs
- `a2ml check <file>` - Quick syntax check
- `a2ml format <file>` - Format according to style guide
- `a2ml convert <from> <to> <file>` - Convert between formats
- `a2ml stats <file>` - Document statistics

=== REPL Commands

- `:load <file>` - Load A2ML document
- `:parse <text>` - Parse A2ML text
- `:validate` - Validate current document
- `:show` - Show current document
- `:convert <fmt>` - Convert to format
- `:save <file>` - Save current document

=== Format Converters

- **Markdown**: CommonMark output
- **HTML**: HTML5 with semantic markup
- **Djot**: Djot with {#id} attributes
- **LaTeX**: Complete document with hyperref
- **PlainText**: Content-only export

== Breaking Changes from v0.x

=== 1. Idris2 Core Required

v0.x had a ReScript prototype. v1.0.0 uses Idris2 for the formal core.

**Migration**: Install Idris2 (https://idris-lang.org)

=== 2. Stricter Validation

v0.x allowed unresolved references in lax mode. v1.0.0 enforces resolution in checked/attested modes.

**Migration**: Ensure all `@ref()` calls resolve to existing IDs.

=== 3. Changed Directive Syntax

v0.x: `@abstract` (no colon)
v1.0.0: `@abstract:` (with colon)

**Migration**: Add `:` to all directive headers.

=== 4. Removed Experimental Features

- Removed: `@meta` directive (use front matter instead)
- Removed: Inline math (use `@opaque(lang="latex")` for now)

=== 5. CLI Exit Codes

v0.x returned 0 on parse errors. v1.0.0 uses proper exit codes:

- `0`: Valid document
- `1`: Validation errors
- `2`: Parse errors
- `3`: File not found

**Migration**: Update CI scripts to check exit codes.

== Migration Guide

=== From v0.6.0 to v1.0.0

==== Step 1: Update Directive Syntax

[source,bash]
----
# Add colons to directives
sed -i 's/@abstract$/@abstract:/' *.a2ml
sed -i 's/@refs$/@refs:/' *.a2ml
sed -i 's/@end$/@end/' *.a2ml  # @end stays the same
----

==== Step 2: Validate IDs and References

[source,bash]
----
# Check for unresolved references
a2ml validate your-doc.a2ml

# Fix errors:
# - Add missing sections for unresolved @ref() calls
# - Ensure all sections have unique IDs
----

==== Step 3: Update Build Scripts

[source,diff]
----
- # v0.x (ReScript)
- rescript build
- node prototype/rescript/src/cli.bs.js validate doc.a2ml

+ # v1.0.0 (Idris2)
+ idris2 --build a2ml.ipkg
+ build/exec/a2ml validate doc.a2ml
----

==== Step 4: Test Rendering

[source,bash]
----
# Generate HTML to verify no rendering regressions
a2ml convert a2ml html your-doc.a2ml > output.html

# Compare with v0.x output
diff v0-output.html output.html
----

=== From Markdown to A2ML

==== Step 1: Convert Syntax

[source,bash]
----
# Headings: already compatible
# (no changes needed)

# Code blocks: add @opaque wrapper
# Before (Markdown):
```python
print("Hello")
```

# After (A2ML):
@opaque(lang="python"):
print("Hello")
@end
----

==== Step 2: Add Metadata

[source,a2ml]
----
# Your Document Title

@abstract:
This is the abstract/summary of your document.
@end

# ... rest of document ...

@refs:
[1] Citation 1
[2] Citation 2
@end
----

==== Step 3: Validate

[source,bash]
----
a2ml validate converted-doc.a2ml
----

== Known Issues

=== v1.0.0 Limitations

1. **LSP server**: Architecture defined, implementation planned for v1.1
2. **Incremental parsing**: Not yet implemented, full reparse on change
3. **Parallel validation**: Single-threaded, planned for v1.1
4. **Windows support**: Not tested, Linux/macOS only

=== Workarounds

- **LSP**: Use CLI in watch mode for now
- **Large docs**: Use `a2ml check` (faster) instead of `validate`
- **Windows**: Use WSL2 or wait for v1.1

== Deprecations

The following features are deprecated and will be removed in v2.0.0:

- **ReScript prototype**: Replaced by Idris2 core
- **v0.x directive syntax**: Use `:` on directive headers

== Security

=== Security Audit

- **Fuzz testing**: 100+ random inputs, no crashes
- **Input validation**: All user input validated
- **Memory safety**: Idris2 guarantees (no buffer overflows)
- **Opaque payloads**: Not executed by default

=== CVEs

No known security vulnerabilities in v1.0.0.

Report security issues to: j.d.a.jewell@open.ac.uk

== Upgrade Path

| Current Version | Upgrade Path | Notes |
|-----------------|--------------|-------|
| v0.1.0 | → v0.6.0 → v1.0.0 | Two-step upgrade |
| v0.5.0 | → v0.6.0 → v1.0.0 | Two-step upgrade |
| v0.6.0 | → v1.0.0 | Direct upgrade |

== Package Availability

=== Official Packages

- [x] **Source**: github.com/hyperpolymath/a2ml
- [x] **Homebrew**: `brew install a2ml` (submitted)
- [ ] **AUR**: `yay -S a2ml` (planned)
- [ ] **Nix**: `nix-env -iA nixpkgs.a2ml` (planned)
- [ ] **Cargo**: `cargo install a2ml` (v1.1)

=== Build from Source

[source,bash]
----
# Clone repository
git clone https://github.com/hyperpolymath/standards.git
# Note: A2ML is located in standards/a2ml
cd a2ml

# Build CLI
cd cli
./build.sh

# Install
sudo cp ../build/exec/a2ml /usr/local/bin/
----

== Documentation

=== New Documentation

- **IDRIS2-CORE.adoc**: Formal core implementation
- **TOOLING.adoc**: Complete tooling guide
- **PERFORMANCE.adoc**: Benchmarks and optimization
- **MIGRATION-GUIDE.adoc**: v0.x → v1.0.0 migration

=== Updated Documentation

- **SPEC.adoc**: Updated to reflect v1.0.0
- **README.adoc**: Updated with v1.0.0 features
- **CONFORMANCE.adoc**: v1.0.0 conformance criteria

== Testing

=== Test Coverage

- **Unit tests**: 29 tests (src/A2ML/Tests.idr)
- **Conformance tests**: Full spec coverage
- **Stress tests**: RFC-sized documents (1.8MB)
- **Fuzz tests**: 100+ random inputs

=== CI/CD

- **GitHub Actions**: Validate on every push
- **Benchmarks**: Track performance regressions
- **Release automation**: Automated builds for Linux/macOS

== Contributors

**Core Team**:
- Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

**Co-Authored-By**:
- Claude Sonnet 4.5 <noreply@anthropic.com>

== License

PMPL-1.0-or-later

See LICENSE for details.

== Acknowledgments

- Idris2 community for the powerful type system
- Djot for inspiration on lightweight markup
- Markdown community for establishing the baseline

== What's Next

=== v1.1.0 Roadmap (Q2 2026)

- LSP server implementation
- Incremental parsing
- Parallel validation
- Windows support
- VS Code extension

=== v2.0.0 Vision (2027)

- JIT compilation
- GPU-accelerated parsing
- Multi-file projects
- Advanced attestation (blockchain)

---

**Released:** 2026-01-30
**Author:** Jonathan D.A. Jewell
**Co-Authored-By:** Claude Sonnet 4.5
