<!-- AI -->
# Use AI around AEON without blurring where authority lives.
## AEON is useful around AI because it keeps claims explicit.
An AI can read or write AEON as ordinary text, while tools around the model can validate structure, resolve references, preserve semantic comments, and produce deterministic receipts.
The useful frame is not a ladder of AI authority. It is a set of boundaries: understanding AEON, implementing AEON, using AEON for agentic exchange, auditing through AEON, and carrying AEON-shaped context.
- **Understanding** I want AI to help me understand AEON before I rely on it.
- **Implementing** I write my own code and use AI to help me build, test, and integrate it.
- **Agentic** I want AI to act through typed, validated request shapes instead of vague prose.
- **Audit** I let AI use tools, but I need a record of what actually happened.
- **Context** I want AI to reason over structured AEON-shaped notes inside the conversation.
<!-- Level I Understanding AEON -->
## Using AI to understand AEON.
In this mode, the author may still be hand coding. AI is used as a language-understanding assistant: it explains syntax, compares AEON with familiar formats, and helps the author reason about source meaning without taking over implementation.
Assume the AI has not been trained on AEON. The author should give it a small reference pack before asking questions, then ask it to cite the supplied material instead of guessing from similar languages.
### Language Understanding Prompt
```
You are helping me understand AEON.
Context:
You may not have AEON-specific training data. Treat the supplied AEON references as authoritative, and say when an answer is not supported by those references.
Supplied references:
- Read this first, semantic preservation primer: https://aeon.altopelago.com/rag-understanding-aeon.php?format=markdown
- Read this second, orthogonal grammar composition primer: https://aeon.altopelago.com/orthogonal-composition.php?format=markdown
- Start here, basic language walkthrough: https://aeon.altopelago.com/walkthrough.php?format=markdown
- Why AEON: https://aeon.altopelago.com/why-aeon.php?format=markdown
- AEON language reference: https://aeon.altopelago.com/aeon-language.php?format=markdown
- Value types: https://aeon.altopelago.com/value-types.php?format=markdown
- Type reference: https://aeon.altopelago.com/type-reference.php?format=markdown
- Processing walkthrough: https://aeon.altopelago.com/walkthrough-processing.php?format=markdown
- Annotation walkthrough: https://aeon.altopelago.com/walkthrough-annotations.php?format=markdown
Reading order:
Start with the semantic preservation primer and orthogonal grammar composition primer. Then use the basic language walkthrough to introduce AEON step by step: a binding, scalar values, optional type labels, objects, lists, tuples, whitespace, comments, and multiline strings. Only move to references, processing, annotations, schemas, or ecosystem topics after the basic document model is clear.
Working model:
AEON is a human-readable, typed, semantics-first data notation. It is designed for documents that need structure, references, validation, source-aware diagnostics, and deterministic processing without giving the document executable authority.
Boundaries:
- Do not assume AEON behaves like JSON, YAML, TOML, Markdown, or code unless the supplied references explicitly say so.
- Do not invent AEOS schema rules; only describe AEOS behavior when the supplied references explicitly define it.
- When uncertain, state the uncertainty instead of guessing.
- Cite references inline using short source labels and section/page names, for example: [Language walkthrough: Bindings].
Explain:
- What problem AEON solves compared with JSON, YAML, Markdown, and code.
- How typed bindings, objects, lists, tuples, references, nodes, annotations, and semantic comments fit together.
- Why deterministic processing matters when humans and AI systems both touch the same source.
- Where AEOS schemas, profiles, annotation streams, and Tonics belong in the ecosystem.
Style:
Be precise, avoid hype, and separate what AEON source says from what trusted processors prove.
```
<!-- Level II Implementing AEON -->
## Using AI to help code deterministic AEON integrations.
In this mode, the author is using AI to help code some or all of an AEON integration into their project. The AI may draft adapters, schemas, fixtures, tests, and runtime calls, but the code itself remains deterministic and prescriptive.
The important boundary is that AI can assist development, while parser behavior, validation rules, reference handling, and emitted application data are accepted only through deterministic code and tests.
Again, assume the AI has not been trained on AEON implementation details. Give it implementation references, examples, and conformance expectations before asking it to write code.
### Implementation Assistance Prompt
```
You are helping me implement AEON tooling.
Context:
You may not have AEON-specific training data. Use only the supplied references and local project files as the basis for implementation advice. If a behavior is not specified, ask for the relevant reference or mark it as an assumption.
Supplied references:
- Read this first, semantic preservation primer: https://aeon.altopelago.com/rag-understanding-aeon.php?format=markdown
- Read this second, orthogonal grammar composition primer: https://aeon.altopelago.com/orthogonal-composition.php?format=markdown
- Developer start: https://aeon.altopelago.com/developer-start.php?format=markdown
- Processing walkthrough: https://aeon.altopelago.com/walkthrough-processing.php?format=markdown
- Schemas: https://aeon.altopelago.com/schemas.php?format=markdown
- AEOS playground notes: https://aeon.altopelago.com/aeos-playground.php?format=markdown
- Type reference: https://aeon.altopelago.com/type-reference.php?format=markdown
- Current versions and repositories: https://aeon.altopelago.com/versions.php?format=markdown
- AEON specification: https://github.com/aeonite-org/aeonite-specs
- CTS: https://github.com/aeonite-org/aeonite-cts
- TypeScript implementation: https://github.com/AltoPelago/aeon
Working model:
Treat AEON as a source language with explicit parsing, validation, diagnostics, canonicalization, and materialization phases. Do not infer meaning from loose prose when a typed binding, schema rule, reference, or annotation can carry it explicitly.
Boundaries:
- Do not infer missing AEON semantics from JSON, YAML, TOML, Markdown, or code.
- Do not define canonical form yourself; canonical behavior belongs to the AEON specification and CTS.
- When the supplied references do not define a behavior, state the uncertainty and propose a test or reference check.
Implementation goals:
- Preserve source spans for diagnostics and annotation streams.
- Parse comments and semantic instruction comments without mixing them into application data.
- Keep validation deterministic and fail closed for strict profiles.
- Resolve references through a specified processor step, not through model intuition.
- Emit plain application output only after syntax, typing, references, and schema/profile checks have passed.
- Add tests for canonical form, invalid fixtures, reference boundaries, and round-trip-safe examples.
Safety boundary:
An AI assistant may draft code and fixtures, but the implementation must be accepted by deterministic tests, validators, and published conformance cases.
```
<!-- Level III Agentic AEON -->
## Using typed AEON-shaped actions to reduce corrupt AI output.
Here, the AI interfaces with tools, APIs, or workflow systems to produce outcomes. Explicit typing, required fields, schema checks, and clear error messages help ensure the AI is not sending corrupt, incomplete, or ambiguous data into the system.
AEON is useful here as an instruction and exchange shape: the AI can be asked to produce typed source, the system can validate it deterministically, and diagnostics can be returned to the AI for correction before any action is accepted.
### Typed API Request
```aeon
request:object = {
action:string = "create_invoice"
customer_id:string = "cus_1738"
currency:string = "AUD"
line_items:list<object> = [
{
description:string = "AEON integration support"
quantity:number = 2
unit_price:number = 180.00
}
]
due_date:string = "2026-06-15"
}
```
### Deterministic Error Feedback
```
validation:error = {
path:string = "/request/line_items/0/unit_price"
expected:string = "decimal currency amount with two fractional digits"
received:string = "number"
message:string = "Use a currency-safe decimal string, for example \"180.00\"."
}
```
- **Type** The AI has a concrete output shape to satisfy instead of a vague natural-language target.
- **Error** The system returns exact, source-local feedback that the AI can use to repair the request.
- **Boundary** The API receives only data that passes deterministic validation, not whatever the model happened to phrase plausibly.
<!-- Level IV Audit thru AEON -->
## Auditing AI control over a run environment.
In this mode, the author gives the AI control of a run environment: for example, a filesystem plus a set of tools it can independently choose from. A signed AEON ledger gives reviewers an audit trail showing which tools were actually used and which outputs were produced.
The ledger does not prove the AI reasoned correctly. It helps verify recorded computations and artifacts against signed tool events rather than accepting hallucinated outputs at face value.
The ledger is an audit boundary, not a security boundary. Access control, sandboxing, secret handling, and permission policy still belong to the surrounding run environment.
Annotation streams may accompany a ledger when reviewers need source-local notes, operator comments, or processor guidance, but the core audit record is the signed event ledger itself.
### Run Environment Ledger
```aeon
run:object = {
id:string = "agent-run-2026-05-28T03:12:00Z"
objective:string = "inspect repository and summarize failing tests"
environment:object = {
filesystem_root:string = "/workspace/project"
allowed_tools:list<string> = ["rg", "pnpm test", "node"]
}
ai_claim:object = {
provider:string = "example-ai"
model:string = "reasoning-model"
prompt_digest:string = "sha256:a817..."
final_answer_digest:string = "sha256:ee91..."
}
tool_events:list<object> = [
{
tool:string = "rg"
args:list<string> = ["failing test"]
stdout_digest:string = "sha256:31cc..."
exit_code:number = 0
},
{
tool:string = "pnpm test"
args:list<string> = []
stdout_digest:string = "sha256:4a92..."
stderr_digest:string = "sha256:00ad..."
exit_code:number = 1
},
{
tool:string = "node"
args:list<string> = ["scripts/explain-failure.mjs"]
stdout_digest:string = "sha256:9c20..."
exit_code:number = 0
}
]
receipts:list<object> = [
{
event:number = 0
canonical_event_digest:string = "sha256:b645..."
signature:string = "ed25519:..."
},
{
event:number = 1
canonical_event_digest:string = "sha256:6f7a..."
signature:string = "ed25519:..."
},
{
event:number = 2
canonical_event_digest:string = "sha256:f35b..."
signature:string = "ed25519:..."
}
]
}
```
- **Control** The ledger records tool choice, arguments, exit codes, output digests, and environment boundaries.
- **Receipt** A receipt signs each canonical event, so reviewers can verify that recorded outputs came from actual tool runs.
- **Boundary** The proof is about execution and artifact identity, not about the AI being inherently trustworthy or the ledger acting as a sandbox.
<!-- Level V AEON in Context -->
## Letting AI work with AEON-shaped text inside its own context.
In this mode, the author lets the AI reason over AEON-shaped material inside the model context itself. There is no assumption that AEON Core, AES, a parser, or a runtime is executing.
AEON is being used as structured language: a readable way for the model to create, edit, compare, and reason about typed claims in context.
Semantic instruction comments help the AI organize and prompt itself on how to handle nearby AEON-shaped text without becoming ordinary data fields.
### Instruction Comment Example
```aeon
planning_note:object = {
/( processor = "ai"
intent = "organize_context"
rule = "Group facts, questions, and assumptions separately. Do not turn assumptions into facts." )/
facts:list<string> = [
"AEON source can carry typed bindings.",
"Semantic instruction comments are guidance for the AI in this context."
]
questions:list<string> = [
"Which references define the current behavior?",
"Which claims need deterministic verification later?"
]
assumptions:list<string> = [
"The author wants a concise explanation unless they ask for implementation detail."
]
response_plan:list<string> = [
"Answer only from facts first.",
"Label assumptions explicitly.",
"Ask for missing references before making language-level claims."
]
}
```
### How the AI should process it
```
Treat the AEON-shaped text as structured language inside your context, not as executable code.
Do not assume an AEON parser, AEON Core, AES, a validator, or a runtime is available.
Use the semantic instruction comment as guidance for your own reasoning.
Keep facts, questions, assumptions, and response plans distinct.
Do not move semantic instruction comments into the data fields you are summarizing.
```
### Data Editing Example
```aeon
customer_summary:object = {
/( processor = "ai"
intent = "edit"
rule = "Improve clarity without changing field names or inventing values." )/
name:string = "Example Studio"
status:string = "active"
note:string = "Needs migration plan before launch."
}
```
```
The AI may rewrite the note for clarity inside its response, but it should preserve field identity and avoid inventing new operational facts.
```