![\"author\"](\"https://github.githubassets.com/images/gravatars/gravatar-user-420.png?size=40\"){kind=avatar}
Architecture Compilation Language
\nIf the compiler cannot explain why it generated a line, it should not generate it.\nAnd this property must be independently verifiable without trusting the compiler.
\n![\"Version\"](\"https://img.shields.io/badge/version-2.0.0-blue.svg\"){kind=icon}
![\"Status\"](\"https://img.shields.io/badge/status-beta-green.svg\"){kind=icon}
![\"Python\"](\"https://img.shields.io/badge/python-3.10+-3776AB.svg?logo=python&logoColor=white\"){kind=icon}
![\"Tests\"](\"https://img.shields.io/badge/tests-151%20passing-brightgreen.svg\"){kind=icon}
![\"Audit\"](\"https://img.shields.io/badge/audit%20coverage-100%25-brightgreen.svg\"){kind=icon}
![\"Proof\"](\"https://img.shields.io/badge/proof%20of%20origin-verifiable-brightgreen.svg\"){kind=icon}
![\"Targets\"](\"https://img.shields.io/badge/targets-Python%20%7C%20Rust%20%7C%20JS%20%7C%20Go-blue.svg\"){kind=icon}
![\"AI\"](\"https://img.shields.io/badge/AI-self%20writing-orange.svg\"){kind=icon}
![\"License\"](\"https://img.shields.io/badge/license-MIT-purple.svg\"){kind=icon}
Install · Quick Start · Proof of Origin · Autonomous Compilation · AI Self-Writing · Language Reference · Grammar · White Paper
\n\n\n
Every 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.
\n3:00 AM pages happen because risks were documented in Confluence, not compiled into code.
\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
AICL is built on five key properties:
\n- \n
- Mandatory Risk/Recovery — Every
Riskmust have aRecovery. Error handling is not optional. \n - Validation → Tests — Every
Validationsection generates a test. Test coverage is structural. \n - Explainable Artifacts — Every generated line of code has a traceable provenance chain. \n
- Measurable Audit Coverage — Audit coverage = auditable artifacts / total artifacts. Target: 100%. \n
- Independently Verifiable Proofs — Proof of Origin files can be verified without the compiler. \n
\n\n
The 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.
AICL Source → Compiler → Proof of Origin\n ├─ Code (Python, Rust, JS, Go)\n ├─ Explain (provenance chains)\n └─ Audit (coverage verification)\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
The independent verifier (tools/verify_proof.py) is ~200 lines of Python using only the standard library — zero AICL dependencies. It performs 8 verification checks:
| # | \nCheck | \nWhat it verifies | \n
|---|---|---|
| 1 | \nformat_version | \nProof format is supported | \n
| 2 | \nsource_hash_binding | \nSHA-256(source_text) == source_hash | \n
| 3 | \nprogram_hash_binding | \nSHA-256(generated_source) == program_hash | \n
| 4 | \ntest_hash_binding | \nSHA-256(generated_tests) == test_hash | \n
| 5 | \nno_orphan_artifact_property | \nEvery artifact has a provenance chain | \n
| 6 | \ncomplete_coverage_property | \nAudit coverage = 1.0 | \n
| 7 | \nrecord_artifact_linkage | \nProvenance records reference valid artifacts | \n
| 8 | \nartifact_consistency | \nOrphan status matches provenance linkage | \n
python tools/verify_proof.py output/main.aicl-proof\n# → VALID (exit 0) or INVALID (exit 1)This eliminates the \"Trust me bro\" problem: AICL says AICL is correct. The independent verifier says the proof is valid — without using AICL.
\n\nThe proof file is self-contained 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}Proof files can be cryptographically signed with the compiler's key:
\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\"] == TrueCross-compilation proof chains link successive compilations, creating an auditable history.
\n\n\n\n
A program is auditable if every generated artifact can be traced to its originating specification through a complete provenance chain:
\nAudit Coverage = Auditable Artifacts / Generated Artifacts\nTarget: Audit Coverage = 1.0\n- \n
- The No-Orphan Property: Every generated artifact has at least one provenance record. \n
- The Complete Coverage Property: Audit coverage equals 1.0 (100%). \n
- The Hash Binding Property: SHA-256 hashes bind the proof to the generated code. \n
These 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
AICL 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 ┌───────────┐\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\nThe loop converges when all of the following are true:
\n- \n
- Spec verification passes (completeness, coherence, satisfaction) \n
- Audit coverage = 1.0 (no orphan artifacts) \n
- All generated tests pass (test pass rate = 100%) \n
- No fallback compilations remain (every behavior compiled deterministically) \n
- Improvement delta < threshold (no further meaningful improvement possible) \n
| Component | \nPurpose | \n
|---|---|
| PatternLearner | \nExtracts verbs/objects from unmatched actions, classifies into 16+ categories, generates templates | \n
| SpecEvolver | \nFixes verification failures, test failures, and audit gaps automatically | \n
| TestRunner | \nRuns pytest, parses output, analyzes failure patterns (imports, attributes, types, assertions) | \n
| LoopController | \nManages convergence detection, max iterations, composite scoring | \n
| AutonomousCompiler | \nOrchestrates the full loop with evolve() method | \n
The 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
The SpecEvolver automatically fixes AICL specifications based on three types of feedback:
\n- \n
- Verification failures: Missing risk/recovery pairs, missing actions, incomplete specifications \n
- Test failures: Missing imports, attributes, definitions, type signatures \n
- Audit gaps: Coverage below 1.0, orphan artifacts \n
All spec changes are tracked with ProvenanceType.SPEC_EVOLVED, maintaining the provenance chain even as the specification itself evolves.
aicl evolve banking.aicl --max-iterations 10\naicl evolve banking.aicl --watch # continuous mode\n\n
The SelfWritingCompiler is the highest level of the AICL system. Given any task description, it can:
\n- \n
- Generate a complete AICL specification from scratch \n
- Compile it through the autonomous loop \n
- AI-diagnose any failures \n
- AI-fix the specification \n
- Iterate until convergence \n
DESCRIBE → AI-GENERATE → COMPILE → VERIFY → TEST →\nAI-DIAGNOSE → AI-FIX → RECOMPILE → ... → CONVERGE\nIf AI is not available, the system gracefully degrades to the deterministic autonomous loop (PatternLearner + SpecEvolver).
\n\n| Component | \nPurpose | \n
|---|---|
| AICLGenerator | \nCreates complete AICL specs from natural language task descriptions | \n
| AIDiagnoser | \nAI-powered root cause analysis and repair of compilation failures | \n
| SelfWritingCompiler | \nOrchestrates the full AI-enhanced loop with create() and evolve() | \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.aiclEvery AI-generated artifact maintains the No-Orphan Property through new provenance types:
\n| ProvenanceType | \nWhen Used | \n
|---|---|
AI_GENERATION | \nCode generated by AI-assisted fallback | \n
SELF_HEALING | \nCode fixed by autonomous diagnosis | \n
PATTERN_LEARNED | \nNew pattern learned from unmatched actions | \n
SPEC_EVOLVED | \nSpecification modified by autonomous evolution | \n
\n\n
AICL v2.0 supports four target languages:
\n| Target | \nStatus | \nFeatures | \n
|---|---|---|
| Python | \nMature (default) | \nFull provenance, pytest tests, dataclasses | \n
| Rust | \nBeta | \nStructs, Result error types, Cargo.toml, #[test] | \n
| JavaScript | \nBeta | \nES6 classes, Jest tests, package.json, async/await | \n
| Go | \nBeta | \nStructs, error types, go.mod, table-driven tests | \n
aicl compile pong.aicl --target rust\naicl compile pong.aicl --target javascript\naicl compile pong.aicl --target goEach target generator produces idiomatic code with:
\n- \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
The aicl verify command checks specifications at three levels:
- \n
- Completeness: All required elements present (Goal, Layer, Validation) \n
- Coherence: No contradictions or dangling references \n
- Satisfaction: Specification is implementable and testable \n
aicl 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
AICL'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
from 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
pip install aiclOr from source:
\ngit clone https://github.com/AFKmoney/AICL.git\ncd AICL\npip install -e .\n\n\n
Goal 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\naicl compile pong.aicl --output-dir outputOutput:
\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\npython tools/verify_proof.py output/main.aicl-proof\n# → VALIDaicl create \"Build a hospital management system with patient records and appointment scheduling\"aicl evolve banking.aicl --max-iterations 10\naicl evolve banking.aicl --watch # continuous modeaicl 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
AICL has 10 progressive levels, each adding a new architectural dimension:
\n| Level | \nName | \nKeywords | \nPurpose | \n
|---|---|---|---|
| 1 | \nArchitecture | \nGoal, Layer, Validation, Risk, Recovery | \nSystem structure + risk management | \n
| 2 | \nEntities | \nEntity, field: type | \nData structures | \n
| 3 | \nBehaviors | \nBehavior, Input, Output, Action | \nWhat entities do | \n
| 4 | \nConditions | \nWhen, Then | \nReplace if/else with declarative rules | \n
| 5 | \nEvents | \nOn, Do | \nEvent-driven architecture | \n
| 6 | \nConcurrency | \nParallel | \nConcurrent layer execution | \n
| 7 | \nOptimization | \nOptimize, Priority | \nPerformance targets | \n
| 8 | \nLearning | \nLearn, Adapt | \nAdaptive behavior | \n
| 9 | \nSecurity | \nEncrypt, Protect | \nSecurity requirements | \n
| 10 | \nNative Code | \nNative | \nInline code in other languages | \n
27 reserved keywords across all levels.
\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 └──────────────┘\nThe Behavior Pattern Library maps action descriptions to concrete code through 30+ deterministic patterns:
\n| Category | \nPatterns | \nExample | \n
|---|---|---|
| Movement | \nMOVE, MOVE_BALL, REFLECT_VELOCITY, CLAMP_POSITION | \n\"Update paddle position\" → MOVE pattern | \n
| Creation | \nCREATE, INIT_LAYER, CREATE_WINDOW | \n\"Create new game\" → CREATE pattern | \n
| Communication | \nBROADCAST, SEND_MESSAGE | \n\"Transmit message\" → BROADCAST pattern | \n
| Update | \nUPDATE, INCREMENT_SCORE, UPDATE_STATE | \n\"Clamp ball position\" → CLAMP pattern | \n
| Display | \nDISPLAY, RENDER_FRAME, HIGHLIGHT | \n\"Draw game frame\" → RENDER pattern | \n
| Validation | \nVALIDATE, CHECK_COLLISION | \n\"Validate move\" → VALIDATE pattern | \n
| Networking | \nCONNECT, RECONNECT, DISCONNECT | \n\"Connect to server\" → CONNECT pattern | \n
| Persistence | \nSTORE, LOAD | \n\"Save game state\" → STORE pattern | \n
| Security | \nENCRYPT_DATA, PROTECT_ACCESS | \n\"Encrypt message\" → ENCRYPT pattern | \n
| Sync | \nSYNC_STATE, BUFFER_INPUT | \n\"Sync state\" → SYNC pattern | \n
| Game | \nEND_GAME, APPLY_PHYSICS | \n\"End game\" → END_GAME pattern | \n
| Adaptation | \nADAPT_QUALITY, SUGGEST, QUEUE_MESSAGE | \n\"Adapt quality\" → ADAPT pattern | \n
When no pattern matches, the sub-language parser handles explicit action specifications:
\nBehavior MovePaddle\n Input: Player direction string\n Action: assign paddle_position += direction * speed\n clamp paddle_position between 0 and screen_width\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).
\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
AICL tracks 23 provenance types covering every compilation zone:
\n| Type | \nStage | \nPurpose | \n
|---|---|---|
PATTERN_MATCH | \nCode Generation | \nMatched deterministic behavior pattern | \n
SUB_LANGUAGE | \nCode Generation | \nExplicit sub-language specification | \n
FALLBACK | \nCode Generation | \nFallback skeleton (human review needed) | \n
ARCHITECTURE_TEMPLATE | \nCode Generation | \nApplication structure template | \n
DIRECT_MAPPING | \nCode Generation | \nDirect keyword-to-code mapping | \n
RECOVERY_SYNTHESIS | \nRecovery Synthesis | \nAuto-generated recovery logic | \n
VALIDATION_SYNTHESIS | \nTest Generation | \nAuto-generated test from validation | \n
CONDITION_SYNTHESIS | \nCode Generation | \nAuto-generated condition logic | \n
EVENT_SYNTHESIS | \nCode Generation | \nAuto-generated event handler | \n
HELPER_METHOD | \nCode Generation | \nAuto-generated helper/utility method | \n
ENTITY_GENERATION | \nCode Generation | \nEntity class/struct generation | \n
LAYER_INITIALIZATION | \nCode Generation | \nLayer setup code | \n
SECURITY_METHOD | \nCode Generation | \nSecurity-related method | \n
PARALLEL_EXECUTION | \nCode Generation | \nParallel execution setup | \n
RUN_METHOD | \nCode Generation | \nApplication main loop | \n
IMPORT_GENERATION | \nCode Generation | \nImport statement generation | \n
ENTRY_POINT | \nFinal Construction | \nProgram entry point | \n
TEST_GENERATION | \nTest Generation | \nTest method generation | \n
CLASS_STRUCTURE | \nCode Generation | \nClass structure generation | \n
AI_GENERATION | \nAutonomous | \nAI-assisted code generation | \n
SELF_HEALING | \nAutonomous | \nAuto-fixed by autonomous diagnosis | \n
PATTERN_LEARNED | \nAutonomous | \nNew pattern learned from unmatched actions | \n
SPEC_EVOLVED | \nAutonomous | \nSpecification modified by autonomous evolution | \n
\n\n
AICL/\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
The complete language specification is in spec/grammar.md, including:
- \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
The white paper at docs/whitepaper.pdf (v2.0) presents AICL as an Architecture Compilation System with auditable provenance as its central thesis:
- \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
The position paper at 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
- 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
| Version | \nMilestone | \nStatus | \n
|---|---|---|
| v0.1 | \nParser, grammar, Python codegen, 38 tests | \n✅ Done | \n
| v0.2 | \nDeterministic patterns, zero-TODO compilation, provenance | \n✅ Done | \n
| v0.3 | \nSub-language expansion, architecture templates | \n✅ Done | \n
| v0.4 | \nExplicable compilation thesis, provenance-first design, project reorganization | \n✅ Done | \n
| v0.5 | \nAudit system, artifact tracking, 100% audit coverage, orphan detection, aicl audit | \n✅ Done | \n
| v0.6 | \nProof of Origin v1.0, aicl proof command, explain/audit from proof file | \n✅ Done | \n
| v0.7 | \nProof of Origin v2.0 (self-contained), independent verifier, 8 verification checks, No-Orphan as formal property | \n✅ Done | \n
| v0.8 | \nPosition paper: \"The No-Orphan Property: Towards Auditable Code Generation\" | \n✅ Done | \n
| v0.9 | \nSpecification compilation: completeness checking, coherence checking, satisfaction checking, aicl verify | \n✅ Done | \n
| v0.10 | \nMulti-file programs: import and module mechanisms, cross-file provenance | \n✅ Done | \n
| v0.11 | \nCryptographic proof signing: proof files signed with compiler key, proof chain across compilations | \n✅ Done | \n
| v1.0 | \nMulti-language targets (Rust, JavaScript, Go), mature compiler, stable proof format | \n✅ Done | \n
| v1.5 | \nProvenance visualization: interactive D3.js exploration of compilation provenance graphs | \n✅ Done | \n
| v2.0 | \nSelf-healing runtime with automatic recovery execution and runtime provenance | \n✅ Done | \n
| v2.5 | \nMemory management: ultra-simple ownership model derived from Layer/Entity structure | \n✅ Done | \n
| v3.0 | \nAutonomous architecture optimization, specification-driven refactoring | \n✅ Done | \n
| v3.5 | \nAutonomous compilation loop: PatternLearner, SpecEvolver, TestRunner, convergence detection, aicl evolve | \n✅ Done | \n
| v4.0 | \nAI-powered self-writing: SelfWritingCompiler, AICLGenerator, AIDiagnoser, aicl create, aicl ai-fix | \n✅ Done | \n
The roadmap reflects a deepening understanding of what auditable compilation means:
\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\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
Contributions 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
MIT License — see LICENSE for details.
\n\nPhilippe-Antoine
\n\n
\"Traditional compilers generate code. AI generates code without accountability.\nAICL generates code with cryptographic proof of origin — and that proof can be verified by anyone.\nEvery risk has a recovery. Every artifact has provenance. Every proof is independently verifiable.\nEven when the code writes itself, every line has a reason, and that reason is recorded.\nFrom specification to autonomous compilation, the chain is unbroken.\"
\n