| "html": "<html><head><meta name=\"color-scheme\" content=\"light dark\"></head><body><pre style=\"word-wrap: break-word; white-space: pre-wrap;\"><div align=\"center\">\n\n# AICL\n\n**Architecture Compilation Language**\n\n*If the compiler cannot explain why it generated a line, it should not generate it.*\n*And this property must be independently verifiable without trusting the compiler.*\n\n[](https://github.com/AFKmoney/AICL)\n[](https://github.com/AFKmoney/AICL)\n[](https://www.python.org/)\n[](https://github.com/AFKmoney/AICL)\n[](https://github.com/AFKmoney/AICL)\n[](https://github.com/AFKmoney/AICL)\n[](https://github.com/AFKmoney/AICL)\n[](https://github.com/AFKmoney/AICL)\n[](https://github.com/AFKmoney/AICL/blob/main/LICENSE)\n\n[Install](#install) · [Quick Start](#quick-start) · [Proof of Origin](#proof-of-origin) · [Autonomous Compilation](#autonomous-compilation) · [AI Self-Writing](#ai-powered-self-writing-compilation) · [Language Reference](#language-levels) · [Grammar](spec/grammar.md) · [White Paper](docs/whitepaper.pdf)\n\n</div>\n\n---\n\n## Why AICL Exists\n\nEvery production system needs error handling, failure recovery, and validation. Yet in every mainstream language, these are **optional afterthoughts** — scattered across try/catch blocks, buried in documentation, or forgotten entirely.\n\n**3:00 AM pages happen because risks were documented in Confluence, not compiled into code.**\n\nAICL makes risk and recovery **mandatory language elements**. Every Risk must have a Recovery. Every Validation must generate a test. Every generated line must have a traceable provenance chain. And every compilation produces a **Proof of Origin** that can be independently verified without trusting the compiler.\n\n---\n\n## Core Idea\n\nAICL is built on five key properties:\n\n1. **Mandatory Risk/Recovery** — Every `Risk` must have a `Recovery`. Error handling is not optional.\n2. **Validation → Tests** — Every `Validation` section generates a test. Test coverage is structural.\n3. **Explainable Artifacts** — Every generated line of code has a traceable provenance chain.\n4. **Measurable Audit Coverage** — Audit coverage = auditable artifacts / total artifacts. Target: 100%.\n5. **Independently Verifiable Proofs** — Proof of Origin files can be verified without the compiler.\n\n---\n\n## Proof of Origin\n\nThe **Proof of Origin** (`.aicl-proof`) is the central artifact of AICL compilation. It is a self-contained, cryptographically bound file that proves every generated artifact has traceable provenance.\n\n```\nAICL Source → Compiler → Proof of Origin\n ├─ Code (Python, Rust, JS, Go)\n ├─ Explain (provenance chains)\n └─ Audit (coverage verification)\n```\n\n### Architecture Shift\n\nIn v0.7+, the **Proof of Origin** became the central artifact. Code, explanation, and audit are views on the proof:\n\n- **aicl compile** → produces code AND proof\n- **aicl explain --proof** → reads from proof (no compiler needed)\n- **aicl audit --proof** → reads from proof (no compiler needed)\n- **aicl proof --verify** → verifies proof integrity\n\n### Independent Verification\n\nThe independent verifier (`tools/verify_proof.py`) is ~200 lines of Python using **only the standard library** — zero AICL dependencies. It performs 8 verification checks:\n\n| # | Check | What it verifies |\n|---|-------|-----------------|\n| 1 | `format_version` | Proof format is supported |\n| 2 | `source_hash_binding` | SHA-256(source_text) == source_hash |\n| 3 | `program_hash_binding` | SHA-256(generated_source) == program_hash |\n| 4 | `test_hash_binding` | SHA-256(generated_tests) == test_hash |\n| 5 | `no_orphan_artifact_property` | Every artifact has a provenance chain |\n| 6 | `complete_coverage_property` | Audit coverage = 1.0 |\n| 7 | `record_artifact_linkage` | Provenance records reference valid artifacts |\n| 8 | `artifact_consistency` | Orphan status matches provenance linkage |\n\n```bash\npython tools/verify_proof.py output/main.aicl-proof\n# → VALID (exit 0) or INVALID (exit 1)\n```\n\nThis eliminates the **\"Trust me bro\" problem**: AICL says AICL is correct. The independent verifier says the proof is valid — without using AICL.\n\n### Proof Format v2.0\n\nThe proof file is self-contained JSON:\n\n```json\n{\n \"format_version\": \"2.0\",\n \"compiler_version\": \"2.0.0\",\n \"timestamp\": \"2026-06-13T12:00:00Z\",\n \"source_hash\": \"sha256:...\",\n \"program_hash\": \"sha256:...\",\n \"test_hash\": \"sha256:...\",\n \"source_text\": \"Goal ...\",\n \"generated_source\": \"class Application ...\",\n \"generated_tests\": \"def test_ ...\",\n \"records\": [...],\n \"artifacts\": [...],\n \"formal_properties\": {...},\n \"audit_coverage\": {...},\n \"explicability_coverage\": {...}\n}\n```\n\n### Cryptographic Proof Signing (v0.11)\n\nProof files can be cryptographically signed with the compiler's key:\n\n```python\nfrom aicl.crypto_signing import create_signed_proof, verify_signed_proof\n\nsigned = create_signed_proof(proof_dict, key_seed=\"compiler-key\")\nresult = verify_signed_proof(signed)\n# result[\"signature_present\"] == True\n# result[\"proof_hash_valid\"] == True\n```\n\nCross-compilation proof chains link successive compilations, creating an auditable history.\n\n---\n\n## Audit System\n\n### What is Auditability?\n\nA program is **auditable** if every generated artifact can be traced to its originating specification through a complete provenance chain:\n\n```\nAudit Coverage = Auditable Artifacts / Generated Artifacts\nTarget: Audit Coverage = 1.0\n```\n\n### Three Formal Properties\n\n1. **The No-Orphan Property**: Every generated artifact has at least one provenance record.\n2. **The Complete Coverage Property**: Audit coverage equals 1.0 (100%).\n3. **The Hash Binding Property**: SHA-256 hashes bind the proof to the generated code.\n\nThese properties are **verifiable properties of the compilation artifact**, not just features of the compiler. An independent verifier can check them without using AICL.\n\n---\n\n## Autonomous Compilation\n\nAICL v2.0 introduces **autonomous compilation** — a self-writing, self-validating loop where the compiler diagnoses its own failures, fixes its own specifications, learns new patterns, and iterates until convergence.\n\n### The Autonomous Loop\n\n```\n ┌───────────┐\n │ SPEC │\n └─────┬─────┘\n │\n ┌─────▼─────┐\n │ COMPILE │ ───→ Code + Proof of Origin\n └─────┬─────┘\n │\n ┌─────▼─────┐\n │ VERIFY │ ───→ Spec completeness, coherence, satisfaction\n └─────┬─────┘\n │\n ┌─────▼─────┐\n │ TEST │ ───→ Run generated tests, analyze failures\n └─────┬─────┘\n │\n ┌─────▼─────┐\n │ DIAGNOSE │ ───→ Pattern-match failures, classify errors\n └─────┬─────┘\n │\n ┌─────▼─────┐\n │ FIX │ ───→ SpecEvolver fixes spec, PatternLearner learns\n └─────┬─────┘\n │\n ┌─────▼─────┐\n │ RECOMPILE │ ───→ Back to COMPILE with evolved spec\n └─────┬─────┘\n │\n └──→ CONVERGED when audit=100%, tests=100%, fallbacks=0\n```\n\n### Convergence Criteria\n\nThe loop converges when **all** of the following are true:\n1. **Spec verification passes** (completeness, coherence, satisfaction)\n2. **Audit coverage = 1.0** (no orphan artifacts)\n3. **All generated tests pass** (test pass rate = 100%)\n4. **No fallback compilations remain** (every behavior compiled deterministically)\n5. **Improvement delta < threshold** (no further meaningful improvement possible)\n\n### Key Components\n\n| Component | Purpose |\n|-----------|---------|\n| **PatternLearner** | Extracts verbs/objects from unmatched actions, classifies into 16+ categories, generates templates |\n| **SpecEvolver** | Fixes verification failures, test failures, and audit gaps automatically |\n| **TestRunner** | Runs pytest, parses output, analyzes failure patterns (imports, attributes, types, assertions) |\n| **LoopController** | Manages convergence detection, max iterations, composite scoring |\n| **AutonomousCompiler** | Orchestrates the full loop with `evolve()` method |\n\n### Pattern Learning\n\nThe PatternLearner extracts new behavior patterns from unmatched action descriptions:\n\n- **Verb extraction**: 40+ action verbs (create, update, validate, compute, transform, store, load, encrypt, connect, notify, etc.)\n- **Object extraction**: Domain-specific objects (account, transaction, card, loan, user, message, request)\n- **Category classification**: 16+ categories (CREATION, UPDATE, VALIDATE, ROUTE, COMPUTE, TRANSFORM, STORE, LOAD, ENCRYPT, CONNECT, NOTIFY, FINANCIAL, SECURITY, AUDIT, etc.)\n- **Template generation**: Per-category code templates\n- **Confidence tracking**: Learned patterns start at 0.7 (vs deterministic 0.95), distinguishing learned from built-in\n\n### Specification Evolution\n\nThe SpecEvolver automatically fixes AICL specifications based on three types of feedback:\n\n1. **Verification failures**: Missing risk/recovery pairs, missing actions, incomplete specifications\n2. **Test failures**: Missing imports, attributes, definitions, type signatures\n3. **Audit gaps**: Coverage below 1.0, orphan artifacts\n\nAll spec changes are tracked with `ProvenanceType.SPEC_EVOLVED`, maintaining the provenance chain even as the specification itself evolves.\n\n```bash\naicl evolve banking.aicl --max-iterations 10\naicl evolve banking.aicl --watch # continuous mode\n```\n\n---\n\n## AI-Powered Self-Writing Compilation\n\nThe **SelfWritingCompiler** is the highest level of the AICL system. Given any task description, it can:\n\n1. Generate a complete AICL specification from scratch\n2. Compile it through the autonomous loop\n3. AI-diagnose any failures\n4. AI-fix the specification\n5. Iterate until convergence\n\n### The Self-Writing Loop\n\n```\nDESCRIBE → AI-GENERATE → COMPILE → VERIFY → TEST →\nAI-DIAGNOSE → AI-FIX → RECOMPILE → ... → CONVERGE\n```\n\nIf AI is not available, the system gracefully degrades to the deterministic autonomous loop (PatternLearner + SpecEvolver).\n\n### AI Components\n\n| Component | Purpose |\n|-----------|---------|\n| **AICLGenerator** | Creates complete AICL specs from natural language task descriptions |\n| **AIDiagnoser** | AI-powered root cause analysis and repair of compilation failures |\n| **SelfWritingCompiler** | Orchestrates the full AI-enhanced loop with `create()` and `evolve()` |\n\n### CLI Commands\n\n```bash\n# Create a complete AICL program from a description\naicl create \"Build a hospital management system\"\n\n# Create and compile to a specific target\naicl create \"Create an e-commerce platform\" --target rust --output shop.aicl\n\n# Evolve an existing spec with AI enhancement\naicl evolve banking.aicl --max-iterations 10\n\n# AI-powered diagnosis of broken specs\naicl ai-fix --error \"Compilation failed: missing Risk/Recovery pair\"\n\n# AI-powered enhancement of existing specs\naicl ai-fix --enhance --source banking.aicl\n```\n\n### Provenance Preservation\n\nEvery AI-generated artifact maintains the No-Orphan Property through new provenance types:\n\n| ProvenanceType | When Used |\n|----------------|-----------|\n| `AI_GENERATION` | Code generated by AI-assisted fallback |\n| `SELF_HEALING` | Code fixed by autonomous diagnosis |\n| `PATTERN_LEARNED` | New pattern learned from unmatched actions |\n| `SPEC_EVOLVED` | Specification modified by autonomous evolution |\n\n---\n\n## Multi-Language Targets\n\nAICL v2.0 supports **four target languages**:\n\n| Target | Status | Features |\n|--------|--------|----------|\n| **Python** | Mature (default) | Full provenance, pytest tests, dataclasses |\n| **Rust** | Beta | Structs, Result error types, Cargo.toml, #[test] |\n| **JavaScript** | Beta | ES6 classes, Jest tests, package.json, async/await |\n| **Go** | Beta | Structs, error types, go.mod, table-driven tests |\n\n```bash\naicl compile pong.aicl --target rust\naicl compile pong.aicl --target javascript\naicl compile pong.aicl --target go\n```\n\nEach target generator produces idiomatic code with:\n- Error handling from Risk/Recovery pairs\n- Entity structures as language-appropriate types\n- Behavior methods with deterministic patterns\n- Test suites from Validation sections\n- Project configuration files (Cargo.toml, package.json, go.mod)\n\n---\n\n## Specification Verification (v0.9)\n\nThe `aicl verify` command checks specifications at three levels:\n\n1. **Completeness**: All required elements present (Goal, Layer, Validation)\n2. **Coherence**: No contradictions or dangling references\n3. **Satisfaction**: Specification is implementable and testable\n\n```bash\naicl verify pong.aicl # All three checks\naicl verify pong.aicl --completeness # Completeness only\naicl verify pong.aicl --coherence # Coherence only\naicl verify pong.aicl --satisfaction # Satisfaction only\n```\n\n---\n\n## Self-Healing Runtime (v2.0)\n\nAICL's self-healing runtime extends compile-time provenance into execution:\n\n- **Risk monitoring**: Runtime checks detect when risks materialize\n- **Automatic recovery**: Recovery actions execute with retry and backoff\n- **Runtime provenance**: Every event is recorded in a provenance chain\n\n```python\nfrom aicl.runtime import RuntimeEnvironment\n\nenv = RuntimeEnvironment()\nenv.register_risk_recovery(\n \"network_failure\",\n risk_condition=lambda: not check_network(),\n recovery_action=lambda: reconnect(),\n)\nresult = env.run(application_main)\n```\n\n---\n\n## Install\n\n```bash\npip install aicl\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/AFKmoney/AICL.git\ncd AICL\npip install -e .\n```\n\n---\n\n## Quick Start\n\n### 1. Write an AICL program\n\n```aicl\nGoal Build a simple Pong game\n\nLayer Game\n SubLayer Rendering\n SubLayer Physics\n\nEntity Ball\n x: float\n y: float\n dx: float\n dy: float\n\nEntity Paddle\n x: float\n y: float\n\nBehavior MoveBall\n Input: Ball ball\n Action: Update ball position by velocity\n\nBehavior MovePaddle\n Input: Player direction string\n Action: Update paddle position\n\nValidation Ball bounces off walls\n Ball velocity reverses on boundary contact\n\nValidation Paddle stays in bounds\n Paddle position clamped to screen width\n\nRisk Ball goes off screen\n Recovery Clamp ball position to screen bounds\n\nRisk Paddle moves too fast\n Recovery Clamp paddle speed to maximum\n```\n\n### 2. Compile with proof\n\n```bash\naicl compile pong.aicl --output-dir output\n```\n\nOutput:\n```\nCompilation successful\n Output directory: output\n Main file: output/main.py\n Test file: output/test_main.py\n Architecture tree: output/architecture_tree.txt\n Proof of Origin: output/main.aicl-proof\n TODOs remaining: 0\n Fully compiled: Yes\n Audit coverage: 100.0%\n Proof of Origin: VALID\n```\n\n### 3. Verify independently\n\n```bash\npython tools/verify_proof.py output/main.aicl-proof\n# → VALID\n```\n\n### 4. Let the code write itself\n\n```bash\naicl create \"Build a hospital management system with patient records and appointment scheduling\"\n```\n\n### 5. Evolve an existing spec\n\n```bash\naicl evolve banking.aicl --max-iterations 10\naicl evolve banking.aicl --watch # continuous mode\n```\n\n### 6. Compile to other languages\n\n```bash\naicl compile pong.aicl --target rust --output-dir rust_output\naicl compile pong.aicl --target javascript --output-dir js_output\naicl compile pong.aicl --target go --output-dir go_output\n```\n\n---\n\n## Language Levels\n\nAICL has 10 progressive levels, each adding a new architectural dimension:\n\n| Level | Name | Keywords | Purpose |\n|-------|------|----------|---------|\n| 1 | Architecture | `Goal`, `Layer`, `Validation`, `Risk`, `Recovery` | System structure + risk management |\n| 2 | Entities | `Entity`, `field: type` | Data structures |\n| 3 | Behaviors | `Behavior`, `Input`, `Output`, `Action` | What entities do |\n| 4 | Conditions | `When`, `Then` | Replace if/else with declarative rules |\n| 5 | Events | `On`, `Do` | Event-driven architecture |\n| 6 | Concurrency | `Parallel` | Concurrent layer execution |\n| 7 | Optimization | `Optimize`, `Priority` | Performance targets |\n| 8 | Learning | `Learn`, `Adapt` | Adaptive behavior |\n| 9 | Security | `Encrypt`, `Protect` | Security requirements |\n| 10 | Native Code | `Native` | Inline code in other languages |\n\n27 reserved keywords across all levels.\n\n---\n\n## Compilation Pipeline\n\n```\n ┌───────────────┐\n │ AICL Source │\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Specification │ ──→ Parser → AST\n │ Parsing │\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Architecture │ ──→ Structural completeness check\n │ Validation │ (Goal, Layer, Validation present)\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Dependency │ ──→ Layer dependency graph\n │ Analysis │\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Risk │ ──→ Risk/Recovery pairing\n │ Analysis │ (every Risk needs a Recovery)\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Recovery │ ──→ Recovery logic synthesis\n │ Synthesis │ + provenance recording\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Code │ ──→ Target language source + error handling\n │ Generation │ (30+ deterministic patterns)\n │ │ + artifact registration\n │ │ + provenance per artifact\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Test │ ──→ Test suite from Validations\n │ Generation │ + artifact registration\n │ │ + provenance linking\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Optimization │ ──→ Apply Optimize/Priority hints\n └────┬──────────┘\n │\n ┌────▼──────────┐\n │ Final │ ──→ main.py + test_main.py + tree\n │ Construction │ + main.aicl-proof (Proof of Origin)\n │ │ + cryptographic signature\n └──────────────┘\n```\n\n### Deterministic Behavior Compilation\n\nThe **Behavior Pattern Library** maps action descriptions to concrete code through 30+ deterministic patterns:\n\n| Category | Patterns | Example |\n|----------|----------|---------|\n| Movement | MOVE, MOVE_BALL, REFLECT_VELOCITY, CLAMP_POSITION | \"Update paddle position\" → MOVE pattern |\n| Creation | CREATE, INIT_LAYER, CREATE_WINDOW | \"Create new game\" → CREATE pattern |\n| Communication | BROADCAST, SEND_MESSAGE | \"Transmit message\" → BROADCAST pattern |\n| Update | UPDATE, INCREMENT_SCORE, UPDATE_STATE | \"Clamp ball position\" → CLAMP pattern |\n| Display | DISPLAY, RENDER_FRAME, HIGHLIGHT | \"Draw game frame\" → RENDER pattern |\n| Validation | VALIDATE, CHECK_COLLISION | \"Validate move\" → VALIDATE pattern |\n| Networking | CONNECT, RECONNECT, DISCONNECT | \"Connect to server\" → CONNECT pattern |\n| Persistence | STORE, LOAD | \"Save game state\" → STORE pattern |\n| Security | ENCRYPT_DATA, PROTECT_ACCESS | \"Encrypt message\" → ENCRYPT pattern |\n| Sync | SYNC_STATE, BUFFER_INPUT | \"Sync state\" → SYNC pattern |\n| Game | END_GAME, APPLY_PHYSICS | \"End game\" → END_GAME pattern |\n| Adaptation | ADAPT_QUALITY, SUGGEST, QUEUE_MESSAGE | \"Adapt quality\" → ADAPT pattern |\n\nWhen no pattern matches, the **sub-language parser** handles explicit action specifications:\n\n```aicl\nBehavior MovePaddle\n Input: Player direction string\n Action: assign paddle_position += direction * speed\n clamp paddle_position between 0 and screen_width\n```\n\nWhen even the sub-language can't help, the **PatternLearner** extracts the action's verb and object, classifies it into a category, and generates a learned template at confidence 0.7 (vs deterministic 0.95).\n\nThis means **zero TODOs** in compiled output. Every behavior compiles to real, executable code — and every compilation decision is recorded in the provenance chain.\n\n---\n\n## Provenance Types\n\nAICL tracks 23 provenance types covering every compilation zone:\n\n| Type | Stage | Purpose |\n|------|-------|---------|\n| `PATTERN_MATCH` | Code Generation | Matched deterministic behavior pattern |\n| `SUB_LANGUAGE` | Code Generation | Explicit sub-language specification |\n| `FALLBACK` | Code Generation | Fallback skeleton (human review needed) |\n| `ARCHITECTURE_TEMPLATE` | Code Generation | Application structure template |\n| `DIRECT_MAPPING` | Code Generation | Direct keyword-to-code mapping |\n| `RECOVERY_SYNTHESIS` | Recovery Synthesis | Auto-generated recovery logic |\n| `VALIDATION_SYNTHESIS` | Test Generation | Auto-generated test from validation |\n| `CONDITION_SYNTHESIS` | Code Generation | Auto-generated condition logic |\n| `EVENT_SYNTHESIS` | Code Generation | Auto-generated event handler |\n| `HELPER_METHOD` | Code Generation | Auto-generated helper/utility method |\n| `ENTITY_GENERATION` | Code Generation | Entity class/struct generation |\n| `LAYER_INITIALIZATION` | Code Generation | Layer setup code |\n| `SECURITY_METHOD` | Code Generation | Security-related method |\n| `PARALLEL_EXECUTION` | Code Generation | Parallel execution setup |\n| `RUN_METHOD` | Code Generation | Application main loop |\n| `IMPORT_GENERATION` | Code Generation | Import statement generation |\n| `ENTRY_POINT` | Final Construction | Program entry point |\n| `TEST_GENERATION` | Test Generation | Test method generation |\n| `CLASS_STRUCTURE` | Code Generation | Class structure generation |\n| `AI_GENERATION` | Autonomous | AI-assisted code generation |\n| `SELF_HEALING` | Autonomous | Auto-fixed by autonomous diagnosis |\n| `PATTERN_LEARNED` | Autonomous | New pattern learned from unmatched actions |\n| `SPEC_EVOLVED` | Autonomous | Specification modified by autonomous evolution |\n\n---\n\n## Project Structure\n\n```\nAICL/\n├── src/aicl/ # Compiler source (~13,700 lines)\n│ ├── __init__.py # Package exports (v2.0.0)\n│ ├── cli.py # CLI: 13 commands (compile, parse, tree, check, explain, audit, proof, verify, optimize, evolve, create, ai-fix, tui, version)\n│ ├── parser.py # Line-based parser → AST\n│ ├── ast.py # 17 AST node dataclasses\n│ ├── ir.py # Intermediate representation (Architecture Tree)\n│ ├── compiler.py # 9-stage compilation pipeline + artifact tracking\n│ ├── patterns.py # 30+ deterministic behavior patterns\n│ ├── provenance.py # Provenance tracker + audit + Proof of Origin (23 types)\n│ ├── lexer.py # Lexical analyzer (standalone)\n│ ├── spec_verify.py # Specification verification (completeness, coherence, satisfaction)\n│ ├── modules.py # Multi-file module system + cross-file provenance\n│ ├── crypto_signing.py # Cryptographic proof signing + proof chains\n│ ├── runtime.py # Self-healing runtime with automatic recovery\n│ ├── ownership.py # Memory management: ownership model from Layer/Entity\n│ ├── auto_optimizer.py # Autonomous architecture optimization\n│ ├── autonomous.py # Self-writing, self-validating compilation loop\n│ ├── ai_generator.py # AI-powered code generation, diagnosis, and self-writing\n│ └── targets/ # Multi-language target generators\n│ ├── __init__.py # Target registry\n│ ├── base.py # Base class for target generators\n│ ├── rust.py # Rust target (structs, Result, Cargo.toml)\n│ ├── javascript.py # JavaScript target (ES6, Jest, package.json)\n│ └── go.py # Go target (structs, go.mod)\n├── examples/ # Example programs\n│ ├── 01_blue_square.aicl # Level 1 — simple graphics (35 artifacts, 100% audit)\n│ ├── 02_pong.aicl # Levels 1–6 — game with behaviors (52 artifacts, 100% audit)\n│ ├── 03_chat.aicl # Levels 1–9 — full-featured app (58 artifacts, 100% audit)\n│ ├── 04_chess.aicl # Levels 1–9 — complex state (59 artifacts, 100% audit)\n│ └── 05_banking.aicl # Levels 1–10 — complete banking system (100% audit, ~1200 lines generated)\n├── tests/ # Test suite\n│ └── test_aicl.py # 151 tests (all passing, including autonomous compilation tests)\n├── spec/ # Language specification\n│ └── grammar.md # Formal BNF grammar & keyword table\n├── docs/ # Documentation\n│ ├── whitepaper.pdf # White Paper v2.0 (17 sections, autonomous compilation + AI self-writing)\n│ ├── position_paper.md # \"The No-Orphan Property: Towards Auditable Code Generation\" (v2.0)\n│ ├── AICL_User_Manual.pdf # User manual\n│ ├── AICL_CLI_TUI_Manual.pdf # CLI/TUI manual\n│ └── AICL_Editor_Manual.pdf # Editor manual\n├── tools/ # Build and utility scripts\n│ ├── generate_whitepaper.py # White paper PDF generator (v2.0)\n│ ├── verify_proof.py # Independent proof verifier (~200 lines, zero AICL deps)\n│ ├── visualize_provenance.py # Provenance graph visualization (D3.js interactive HTML)\n│ └── ai_bridge.mjs # Node.js bridge for AI integration (z-ai-web-dev-sdk)\n├── pyproject.toml # Python package configuration\n├── LICENSE # MIT License\n├── .gitignore # Git ignore rules\n└── README.md # This file\n```\n\n---\n\n## Formal Specification\n\nThe complete language specification is in [`spec/grammar.md`](spec/grammar.md), including:\n\n- Full BNF grammar for all 10 language levels\n- 27 reserved keywords with level and purpose\n- Type system (`string`, `integer`, `float`, `boolean`, `datetime`, `list`, `dict`, `set`, `any`, `void`, `bytes`)\n- Comment syntax (lines starting with `#`)\n- File extension (`.aicl`)\n\n---\n\n## White Paper\n\nThe white paper at [`docs/whitepaper.pdf`](docs/whitepaper.pdf) (v2.0) presents AICL as an Architecture Compilation System with **auditable provenance** as its central thesis:\n\n- The provenance principle: a compiler that cannot explain why should not generate\n- The No-Orphan Property: every artifact must have traceable provenance\n- The Complete Coverage Property: audit coverage must equal 1.0\n- Proof of Origin: self-contained, cryptographically bound compilation artifact\n- Independent verification: proof verifiable without trusting the compiler\n- The \"Trust me bro\" problem and how independent verification solves it\n- Formal BNF grammar with derivation rules\n- Risk and Recovery as mandatory language elements\n- 23 provenance types covering all compilation zones\n- Deterministic compilation contract\n- Comparative analysis against DSLs, ADLs, and AI code generators\n- **Autonomous compilation**: self-writing, self-validating loop with PatternLearner and SpecEvolver\n- **AI-powered self-writing**: SelfWritingCompiler with AICLGenerator and AIDiagnoser\n- **Banking system example**: Full 10-level demonstration\n- Self-healing runtime: extending provenance into execution\n- Ownership model: memory management from architectural structure\n- Multi-language compilation: one specification, four targets\n\n---\n\n## Position Paper\n\nThe position paper at [`docs/position_paper.md`](docs/position_paper.md) (v2.0) — \"The No-Orphan Property: Towards Auditable Code Generation\" — argues that the No-Orphan Property should be a fundamental requirement for any code generation system:\n\n- The accountability gap in traditional compilers and AI code generators\n- The \"Trust me bro\" problem: systems assert correctness without evidence\n- The No-Orphan Property as a formally verifiable invariant\n- Why independence matters: circular trust vs. mathematical trust\n- **Autonomous compilation preserves the No-Orphan Property**: even self-modifying code has traceable provenance\n- **AI self-writing with provenance**: every AI-generated, learned, and evolved artifact is tracked\n- Implications for AI code generation and software engineering\n- Objections and responses (determinism, overhead, dynamic code, hash binding)\n\n---\n\n## Roadmap\n\n| Version | Milestone | Status |\n|---------|-----------|--------|\n| **v0.1** | Parser, grammar, Python codegen, 38 tests | ✅ Done |\n| **v0.2** | Deterministic patterns, zero-TODO compilation, provenance | ✅ Done |\n| **v0.3** | Sub-language expansion, architecture templates | ✅ Done |\n| **v0.4** | Explicable compilation thesis, provenance-first design, project reorganization | ✅ Done |\n| **v0.5** | Audit system, artifact tracking, 100% audit coverage, orphan detection, `aicl audit` | ✅ Done |\n| **v0.6** | Proof of Origin v1.0, `aicl proof` command, explain/audit from proof file | ✅ Done |\n| **v0.7** | Proof of Origin v2.0 (self-contained), independent verifier, 8 verification checks, No-Orphan as formal property | ✅ Done |\n| **v0.8** | Position paper: \"The No-Orphan Property: Towards Auditable Code Generation\" | ✅ Done |\n| **v0.9** | Specification compilation: completeness checking, coherence checking, satisfaction checking, `aicl verify` | ✅ Done |\n| **v0.10** | Multi-file programs: import and module mechanisms, cross-file provenance | ✅ Done |\n| **v0.11** | Cryptographic proof signing: proof files signed with compiler key, proof chain across compilations | ✅ Done |\n| **v1.0** | Multi-language targets (Rust, JavaScript, Go), mature compiler, stable proof format | ✅ Done |\n| **v1.5** | Provenance visualization: interactive D3.js exploration of compilation provenance graphs | ✅ Done |\n| **v2.0** | Self-healing runtime with automatic recovery execution and runtime provenance | ✅ Done |\n| **v2.5** | Memory management: ultra-simple ownership model derived from Layer/Entity structure | ✅ Done |\n| **v3.0** | Autonomous architecture optimization, specification-driven refactoring | ✅ Done |\n| **v3.5** | Autonomous compilation loop: PatternLearner, SpecEvolver, TestRunner, convergence detection, `aicl evolve` | ✅ Done |\n| **v4.0** | AI-powered self-writing: SelfWritingCompiler, AICLGenerator, AIDiagnoser, `aicl create`, `aicl ai-fix` | ✅ Done |\n\n### The Conceptual Trajectory\n\nThe roadmap reflects a deepening understanding of what auditable compilation means:\n\n```\nv0.1–v0.3: \"I want a simpler language than C++\"\nv0.4–v0.5: \"I want the compiler to explain itself\" → Explicable Compilation\nv0.5–v0.6: \"I want to measure that explanation\" → Auditable Compilation\nv0.7: \"I want proof that doesn't require trust\" → Proof of Origin + Independent Verification\nv0.8: \"This idea transcends AICL itself\" → The No-Orphan Property (Position Paper)\nv0.9: \"I want to verify the specification\" → Specification Compilation\nv0.10: \"I want multi-file programs\" → Module System + Cross-File Provenance\nv0.11: \"I want the proof to be tamper-proof\" → Cryptographic Proof Signing\nv1.0: \"I want it in other languages\" → Multi-Language Targets\nv1.5: \"I want to see the provenance\" → Provenance Visualization\nv2.0: \"I want self-healing at runtime\" → Self-Healing Runtime\nv2.5: \"I want safe memory management\" → Ownership Model\nv3.0: \"I want the architecture to improve itself\" → Autonomous Optimization\nv3.5: \"I want the code to write and validate itself\" → Autonomous Compilation Loop\nv4.0: \"I want it to code itself for any task\" → AI Self-Writing Compiler\n```\n\nEach stage discovered that the previous stage's endpoint was actually the beginning of a deeper problem. Explicable compilation raised the question of measurement. Measurement raised the question of trust. Trust raised the question of independent verification. Verification raised the question of specification quality. Specification raised the question of multi-file programs. Multi-file raised the question of proof integrity. Proof integrity raised the question of language independence. Language independence raised the question of visibility. Visibility raised the question of runtime behavior. Runtime raised the question of memory safety. Memory safety raised the question of architectural evolution. Evolution raised the question of autonomous compilation. Autonomous compilation raised the question of self-writing code. And self-writing code raises the question: can a compiler that writes itself still prove where every line came from? AICL's answer is yes — because provenance is not an afterthought, it is the architecture.\n\n---\n\n## Contributing\n\nContributions are welcome. Areas of particular interest:\n\n- **New target languages** — TypeScript, C++, Java, Kotlin, Swift code generation backends\n- **New behavior patterns** — Expand the deterministic pattern library\n- **IDE support** — Syntax highlighting, LSP server, VS Code extension\n- **New examples** — Real-world programs showcasing different levels\n- **Performance optimization** — Large program compilation speed\n- **Proof format standardization** — Interoperable proof files across tools\n- **Runtime provenance** — Extending provenance to JIT and dynamic code generation\n- **AI integration** — Better prompts, more reliable generation, multi-model support\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n## Author\n\n**Philippe-Antoine**\n\n---\n\n<div align=\"center\">\n\n*\"Traditional compilers generate code. AI generates code without accountability.*\n*AICL generates code with cryptographic proof of origin — and that proof can be verified by anyone.*\n*Every risk has a recovery. Every artifact has provenance. Every proof is independently verifiable.*\n*Even when the code writes itself, every line has a reason, and that reason is recorded.*\n*From specification to autonomous compilation, the chain is unbroken.\"*\n\n</div>\n</pre></body></html>", |
