01 What AIOL is
A narrow answer to a narrow question, not a claim to have solved AI-to-AI communication.
Neither raw human language nor a model's internal representations make a good machine-to-machine contract: human phrasing is ambiguous, and a model's own learned representations aren't a stable, shared vocabulary — one model's encoding generally can't be handed to another and understood. AIOL sits between them. It doesn't replace human language, and it isn't a general-purpose AI language — it's a small, explicit format for one thing: a resolved intent, expressed as a versioned, schema-validated JSON envelope instead of a private, per-application data structure.
The governing design rule is: probabilistic interpretation, deterministic validation and execution. A model — or a deterministic parser, when the phrasing is unambiguous enough not to need one — may propose what a request means. Once that meaning is resolved, the resulting envelope is canonical: it can be validated, tested, versioned, and executed by ordinary code, without asking a model to reinterpret it.
What exists today
- A shared core envelope shape
- Three domain vocabularies: Tasks, Calendar, Grocery
- A Context Capsule structure (FACT / RECALL), with one live producer
- Naro as a working reference implementation, all six live intents fully AIOL-gated
- A conformance test suite validating real function output, not just hand-written examples
- Adoptable optional-field standards (see Section 5)
What doesn't exist yet
- A public repository, website, or hosted schemas
- npm/PyPI packages or an SDK
- A second real implementation to prove interoperability
- Transport bindings (MCP, A2A)
- Authority, provenance, or signature fields
- The REVIEW epistemic mode
That second list isn't a to-do list glossed over — it's the honest boundary of what one internal reference implementation can prove by itself. Section 9 covers what closes each gap.
02 Principles
Five rules every schema and every line of Naro's reference implementation is held to.
Probabilistic interpretation, deterministic validation
A model may propose what a request means. Only deterministic code validates the resulting envelope and performs the write. Interpretation and execution are never the same step.
Refuse, don't guess
An ambiguous reference or an invalid envelope is refused or clarified — never silently resolved to a best guess. A validation failure means zero writes, not a partial one.
Small vocabularies, not enumerated sentences
AIOL defines a compact grammar of intents and arguments. It does not, and will not, hard-code a rule per possible phrasing — equivalent statements normalize to the same canonical intent and arguments, even though the full envelopes around them can still differ.
Optional fields are compatibility signals
An app is never required to implement a field like Task's position. But one that advertises support for it must use AIOL's exact name, enum, and validation rules — letting an AIOL-aware translator or agent address that capability without learning an application-specific alternative. See Section 5.
Evidence before generalization
Every field in every schema traces to a real function Naro's reference implementation actually runs today. Nothing here is speculative, aspirational, or added ahead of a proven need.
03 Envelope & vocabularies
One shared shape; a small number of domain-specific extensions.
Every AIOL message shares the same core envelope — aiol (version), id, intent, arguments, an optional target (present only when the intent resolves free text to one entity), and an optional result (present only once a write has been attempted). A domain vocabulary defines what a given intent string means, what its arguments/result.status may contain, and whether it's actually reachable in the reference implementation today (wired_live) or implemented-and-tested but deliberately not given live traffic.
| Vocabulary | Intents | Wired live |
|---|---|---|
| Core | the shared envelope shape (no intents of its own) | — |
| Tasks | task.complete, task.reschedule, task.create, task.due_today, task.suggest_next | 3 of 5 — the other two are implemented and tested, not yet given live traffic as validated envelopes |
| Calendar | event.create | yes |
| Grocery | grocery.add, grocery.restock | yes, both |
| Context | the Context Capsule structure — not an intent, see Section 6 | yes, one real producer (FACT mode) |
A resolved task-completion request looks like this — the same shape regardless of which of nine real, equivalent phrasings produced it:
// "Mark water the plants done." and eight other verified phrasings all produce this: { "aiol": "0.1", "intent": "task.complete", "target": { "status": "resolved", "resolved_id": "task_101" }, "arguments": { "query": "water the plants" }, "result": { "status": "completed" } }
If the query matches more than one task, target.status becomes "ambiguous" with a list of candidates and no write happens — the same shape carries both the success case and the refusal, so a caller never needs a separate error format.
04 Coverage
Which live routes are actually AIOL-gated, verified against the dispatch code directly, not assumed.
All six intents Naro routes live today end in an AIOL-validated write, but they get there by two different structural patterns:
| Intent | Route(s) to the write | Coverage |
|---|---|---|
| task.complete | A narrow deterministic phrase match, or (as of a later fix) the model's own update_task(is_done=True) tool call — both produce a proposal or precondition-checked write validated against the same envelope before anything is written | Complete |
| task.reschedule | Same shape as above, for due_date changes | Complete |
| task.create | A narrow deterministic fast path, or the model's create_task tool call — both validated before the write | Complete |
| event.create | Always via the model; a human confirms the model's own unmodified proposal before it's validated and written | Complete — one path, always gated |
| grocery.add | Always via the model (or via grocery.restock's resolution, which defers to this same path); same human-confirm-then-validate gate | Complete — one path, always gated |
| grocery.restock | A narrow deterministic phrase match resolves the target; unmatched phrasing falls to grocery.add instead, still gated | Complete — no ungated route exists |
Three different things "model-originated AIOL" could mean
Worth naming precisely, since they're easy to blur together:
- A — model proposal converted to AIOL: the model calls a tool with some arguments → that exact proposal is converted into an AIOL envelope → a human confirms it unmodified → the envelope is validated → the write happens.
- B — human-re-entered data creates AIOL: the model suggests an action, but a human separately edits or re-enters the structured data before anything becomes AIOL.
- C — the model emits AIOL directly: no proposal/tool-call step at all; the model itself produces a schema-shaped envelope, which is then validated and executed.
Condition A is what's real today, for all six intents — traced directly in the reference implementation's frontend and backend code, not inferred: every confirm card renders a plain text summary with no editable fields anywhere; confirming sends the exact proposal object the model's tool call produced, byte-for-byte, to the write path, which is what converts it into an AIOL envelope and validates it. Condition B is not implemented anywhere in the reference implementation — there is no flow where a human edits data before it becomes AIOL. Condition C is confirmed not built anywhere either.
05 Adopting the standard
The part meant for a developer who has never touched Naro or DrezTek.
AIOL's optional fields exist so that a completely independent application can improve its compatibility with an AIOL-aware translator or agent, without adopting Naro, DIL, or anything else DrezTek builds. An application is never required to implement an optional capability — but one that advertises support for it must use AIOL's exact field names, values, and validation rules (where a fixed enum is defined). Using the standardized field lets an AIOL-aware translator or agent address that capability without having to learn an application-specific alternative; it does not mean a model inherently knows AIOL out of the box — the model or agent still has to be given the schema, or connected through something that has been.
Example: Task position & category
Naro's Tasks already support a fixed v1 position enum (focus / quick_win / follow_up) and a free-string category, both optional on the Task entity and on task.create. A request like "Add call dentist to my Domestic list as a Quick Win" only resolves correctly end-to-end because the field name and its three allowed values are standardized — a different task app that added the same position field, using the same three values, would handle that request correctly too, without ever seeing Naro's code.
The enum is deliberately fixed, not an open string, for v1: three apps inventing three different names for "do this soon, low effort" would defeat the entire point of a shared field. A future need for more values is a new schema version, not silent drift on this one.
Example: Grocery existing-item detection
grocery.add's result_status is created or restocked — directly mirroring whether the write found an existing item (by exact name) and flipped it back onto the list, or inserted a genuinely new one. Supporting grocery.add does not by itself mean supporting existing-item detection: an application that never checks for a match, and always reports created, is still valid AIOL — just a lower-capability implementation of the same intent. An application that does detect existing items should advertise that capability and report restocked accurately, so a caller can actually tell the two implementations apart.
Fuzzy matching — resolving "we're out of mayo" against an existing "Mayonnaise" item — is a separate intent, grocery.restock, with its own three-way resolved / ambiguous / none result (the same resolution vocabulary Tasks uses). It never writes on its own: ambiguous is a hard refusal, and resolved/none both produce a proposal that only grocery.add's own write path ever commits, once a human confirms.
06 Context Capsules
The other half of the efficiency story — what a model is actually handed, not just what it's asked to do.
A Context Capsule is a compact, token-budgeted package containing only the context items relevant to one request — never the user's full history or database — with every item explicitly classified by epistemic status (see below). AIOL standardizes the capsule's structure: its relevance and token-budget fields, epistemic status, ordering, provenance, and completeness/truncation information. How a capsule is actually inserted into a model's context — a system message, an MCP resource, an API field, something else — is a separate transport or model-binding concern, not part of the capsule schema itself.
Naro's own reference implementation delivers capsules inline, folded into the same user-message turn, because a discrete capsule block was measured, on Naro's local model, to push prompt evaluation from 0.49s to 19.7s. That's a real reference-implementation finding that motivated Naro's current delivery binding — not an AIOL-wide delivery requirement, and not something every future implementation needs to replicate. One live route (a task-ranking recommendation) now delivers a real FACT-mode capsule this way; see the DrezTek Efficiency Initiative overview for exactly which requests reach it and which still don't.
Every capsule carries an epistemic_mode: FACT (confirmed data — a ranked list of real, existing tasks) or RECALL (candidate, unconfirmed material, quoted with status — a fuzzy journal-search result, explicitly marked confirmed: false). A third mode, REVIEW (a dedicated confirmation path), is named in the design but has no producer anywhere yet — honestly absent from the schema's enum rather than included ahead of need.
A related rule — RECALL material must never feed a write step without an intervening confirmation — is implemented as a real, directly-tested guard function today, even though no live request path yet produces the sequence it protects against (the one RECALL producer in the reference implementation is read-only). The guard exists ahead of its call site on purpose, the same way epistemic_mode itself existed for several versions before RECALL had a real producer.
A capsule's data comes entirely from the producing application's own store today. DIL (DrezTek's separate, already-running shared intelligence layer, used by other DrezTek apps) is a plausible future source for a capsule's data, but is not connected to AIOL or to Naro today — see the DrezTek Efficiency Initiative overview for the real, current status of that question.
07 Verification & conformance
What's actually run, on every change, not asserted in prose.
The specification repository's own test suite (36 tests) checks every schema is well-formed JSON Schema, and that every example fixture — both valid and deliberately invalid — validates the way its own description claims. Naro's backend suite (513 tests as of this page's most recent update) goes further: it validates real function output, not hand-written examples, against these schemas, and proves specific safety properties directly:
- Nine independently-phrased real requests ("Mark water the plants done," "I finished watering the plants," …) all extract the same canonical intent and arguments (
task.complete,query: "water the plants"). The full envelopes around them still differ — message ID, timestamps, and which task is actually resolved at call time are not, and are not meant to be, identical; equivalence is proven at that canonical semantic-projection level, not byte-for-byte across the whole envelope. - A validation failure on any guarded write results in zero database calls — proven by injecting a broken envelope and asserting the underlying write function was never invoked, not just that an error was raised.
- Naro's own vendored schema copy is checked byte-for-byte against this repository's authoritative source, so the two can never silently drift apart in a real development environment.
- A frozen 10-case golden request set (clear phrasings, ambiguous references, missing entities) gates every change: the reference implementation must show zero wrong-writes and 100% correct resolution before a change is considered non-regressive.
| Provable now, one implementation | Blocked until a second exists | |
|---|---|---|
| Correctness | Schema-valid envelopes from real output; equivalent phrasings normalize to the same canonical intent and arguments; invalid envelopes rejected with zero writes | — |
| Interoperability | — | Whether two applications reach the same operational meaning from the same envelope with no re-interpretation; whether different models produce equivalent AIOL for the same request |
| Transport | — | Whether meaning survives unchanged through MCP, A2A, or any other binding |
08 Efficiency & the three-path benchmark
Three separate things produce savings here. Only one measurement design can tell them apart.
"AIOL is efficient" would mix together three genuinely different effects: savings from Naro's deterministic-first routing, savings from Context Capsules' reduced payload, and whatever AIOL's own schema-validation step adds or costs on top of both. Measuring only "before vs. after" would credit AIOL for gains that actually came from the routing architecture underneath it. The reference implementation's evaluation harness avoids that by running every request through three paths, not two:
| Path | What it runs | What it isolates |
|---|---|---|
| A — Agentic baseline | The original model tool-calling loop | Cost and correctness before any of this existed |
| B — Optimized, internal | Deterministic resolvers and Context Capsules, plain internal objects — no AIOL envelope | The value of deterministic-first routing on its own |
| C — Optimized, AIOL-validated | The same resolvers, wrapped in a schema-validated AIOL envelope before any write | AIOL's own marginal cost or benefit on top of B |
A real run against the 10-case golden set (single local run, illustrative, not a controlled benchmark) measured:
| Metric | A — Agentic baseline | B — Optimized, internal | C — Optimized, AIOL |
|---|---|---|---|
| Avg. latency | 4,483 ms | 7 ms | 13 ms |
| Avg. tokens (est.) | 26 | 12 | 15 |
| Correct outcomes | 6 / 10 | 10 / 10 | 6 / 6* |
| Wrong writes | 0 / 10 | 0 / 10 | 0 / 6* |
*Path C's case count reflects this specific golden set's write-safety subset at the time of this run, not a limit on AIOL's own coverage — see Section 4, all six live intents are now AIOL-gated.
Read honestly: essentially all of the latency and token reduction comes from Path B — deterministic routing avoiding a model call at all. Path C's schema-validation step adds real, measurable overhead on top of B (roughly 6ms here) in exchange for a portable, validated result. That's the trade to report plainly, not obscure: AIOL's local cost is small and real; its larger claimed advantage — one resolved meaning reused by multiple applications without each spending tokens to reinterpret it — is exactly the part this single-implementation benchmark structurally cannot measure yet.
Read this as preliminary, not a general performance conclusion. One local run, a rough token estimate, no repeated trials, and no median/p95 reporting all limit what can be claimed today. A newer, second benchmark (measuring a live Context Capsule route against the same baseline) is tracked on the DrezTek Efficiency Initiative overview, alongside the same honesty about what still isn't measured.
09 Status & roadmap
AIOL is 0.1, experimental, DrezTek-initiated, with Naro as its only reference implementation. It is not a public release, not a runtime service, and makes no interoperability claim yet — see Section 1's "what doesn't exist yet."
| Step | Status |
|---|---|
| Core envelope + Tasks/Calendar/Grocery/Context vocabularies | Done |
| Naro reference implementation, validate-before-write gate complete on all six live intents | Done |
| One live Context Capsule (FACT mode) | Done |
| Cross-application proof (a second real implementation) | Not started |
| Model interoperability test (equivalent envelopes across models) | Not started |
| Transport bindings (MCP, A2A) | Not started |
| Public 0.x release (repo, docs site, schema downloads) | Not started |
| 1.0 stabilization | Blocked on outside implementation experience |
10 Who this is for
- Developers. The schemas are static JSON files — vendor them locally, validate your own messages, no network dependency, no account. Start with the optional compatibility fields in Section 5; they're the cheapest way to gain interoperability with anything AIOL-aware.
- Investors and interested entities. Preliminary development measurements from one working, tested reference implementation (Section 8) show a real advantage from deterministic-first routing over naive model-tool-calling, and a small, measurable validation cost from AIOL on top of it — not yet a controlled, general performance conclusion. The claims stop exactly where the evidence stops: no cross-application proof exists yet either, and that gap is stated plainly, not implied away.
- Agents and models. The vocabulary is intentionally small. Propose an interpretation; never assume it's final. A validation failure must not execute. Return a structured error, and request clarification or reformulation when the failure originates in unresolved user input — a failure can just as easily mean a translator or implementation defect, not only an unclear request.