AIX Validator

1. Introduction

1.1 The Problem

Markdown is the most widely used lightweight markup format on the web — and the most fragmented. Twenty-two years after John Gruber introduced it on Daring Fireball in December 2004, no two implementations agree on how to interpret it, no two platforms agree on which flavor extensions to support, and as of the AI era no two generators agree on how to produce it.

The variance has three distinct origins, and each demands a different fix:

1. Original ambiguity — Gruber’s syntax description was deliberately informal. It defined a writing format optimized for human readability, not a machine-precise specification. Sublist indentation, blank-line behavior around blocks, emphasis precedence, and HTML/markdown interaction were never normatively defined.
2. Standardization war — In 2014, John MacFarlane, Jeff Atwood, and collaborators launched Standard Markdown (renamed CommonMark after Gruber’s public objection) to formally specify parser behavior. CommonMark and its GitHub-flavored superset (GFM) are now the de facto standards for parsing, but Gruber never endorsed them, and platforms continue to ship their own flavors (Pandoc Markdown, MultiMarkdown, kramdown, Markdown Extra, R Markdown, Discount, Redcarpet, GitLab Flavored Markdown).
3. Generator chaos — Since 2023, large language models have introduced a new and worse variance source: each major AI chatbot emits markdown in its own house dialect, with characteristic differences in heading structure, bullet markers, list spacing, table conventions, special characters, and copy/export fidelity. Empirical testing of the major commercial chatbots against a single fixed prompt reveals at least 17 measurable formatting dimensions on which they disagree.

CommonMark and GFM fix the second source. AIX Universal Markdown fixes the third.

1.2 Relationship to Prior Work

AIX Universal Markdown is not a parser specification. It does not redefine how existing markdown is interpreted, and it does not compete with CommonMark or GFM. It specifies what AI generators MUST emit, what interfaces MUST preserve, and what copy operations MUST round-trip.

1.3 The Three-Layer Model

Variance between AI markdown outputs has three failure surfaces, and the fixes live in different places:

AIX Universal Markdown specifies normative requirements at all three layers. A conformant implementation MUST satisfy all three. The Cleaner tool published alongside this specification operates at the third layer: it normalizes whatever survives the copy operation back into AIX-conformant markdown. It is the consumer-side defense against vendor-side render and copy failures.

2. Scope

2.1 What This Specification Covers

• The canonical markdown form an AI model MUST emit for each of 17 formatting dimensions where empirical chatbot output diverges
• The render-layer guarantees an AI interface MUST provide so that displayed content matches generated content
• The copy/export-layer guarantees a platform MUST provide so that copied content matches displayed content
• Six validation tests that determine whether a given markdown document conforms to this specification
• A canonical worked example demonstrating compliant output for a fixed test prompt

2.2 What This Specification Does NOT Cover

• How existing markdown should be parsed into HTML or any other format. CommonMark and GFM cover this.
• Which markdown features a generator MAY use beyond the minimum. A generator MAY use any CommonMark or GFM construct; this specification only constrains how those constructs are written.
• How AI providers should authenticate, route, or bill AIX requests. AIX 2.2 covers this.
• Provider-specific extensions (math notation, Mermaid diagrams, custom containers). These remain implementation-defined.

This specification does NOT require any particular author voice, content structure, or response strategy. It governs syntactic emission, not content.

3. Generator Rules (Model Output Layer)

The following 17 rules are normative. AI generators claiming AIX Universal Markdown conformance MUST emit markdown that satisfies every rule. The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and OPTIONAL follow RFC 2119.

# Document Title

## 1. First Section

### Subsection

## 2. Second Section

# Top 5 AI Agent Platforms in 2026

## 1. LangGraph

## 2. CrewAI

## Comparison

### 1. LangGraph

### 2. CrewAI

- First item
- Second item
- Third item

Here is the list:

- First item
- Second item
- Third item

Here is the following paragraph.

- Top-level item
  - Nested item
  - Another nested item
- Next top-level item

1. First step
2. Second step
3. Third step

## 1. LangGraph

LangGraph sits on top of LangChain and provides graph-based orchestration.

### Key features

- Graph-based orchestration
- Durable execution
- Human-in-the-loop checkpointing

Last paragraph of section A.

---

First paragraph of section B.

| Platform | Open source | Self-hosted | Pricing |
| --- | --- | --- | --- |
| LangGraph | Yes | Yes | Free / paid platform |
| CrewAI | Yes | Yes | Free / paid platform |
| AgentKit | No | No | API usage |

| Platform | Open source |
| --- | --- |
| LangGraph | Yes |
| AgentKit | No |
| Dify | Partial: Apache 2.0 with additional conditions |

```python
def hello():
    print(“world”)
```

LangGraph supports durable execution windows of eight hours or more.[1]

## Sources

1. LangGraph Platform documentation, May 2026 — https://docs.langchain.com/langgraph-platform

4. Interface Render Layer Requirements

AI chat interfaces that display AIX Universal Markdown MUST satisfy the following requirements.

4.1 Lossless Rendering

An interface MUST render every structural element present in the markdown source. If the interface cannot render a structural element (e.g. it does not support GFM tables), it MUST display the unrendered markdown source for that element rather than dropping it from the output.

4.2 Visual Encoding Substitution

An interface MAY substitute glyphs, icons, or color encoding for textual cell values (e.g. rendering Yes as a green checkmark) as a display-layer enhancement. The interface MUST preserve the original textual value in any selectable, copyable representation of the table. If an interface renders Yes as ✓, then: the displayed visual MAY show ✓; the selectable text MUST be Yes; the copyable markdown source MUST be the original Yes.

4.3 Markdown Identity Preservation

An interface MUST NOT transform markdown structure into a non-markdown internal representation that is rendered to the user but cannot be serialized back to markdown. Every visible structural element MUST be recoverable as markdown via copy or export.

4.4 Visible Source Disclosure

An interface SHOULD provide a “view source” or “copy as markdown” affordance that gives the user direct access to the AIX Universal Markdown source as emitted by the generator.

5. Copy / Export Layer Requirements

5.1 Round-Trip Fidelity

When a user copies all or part of an AI response containing AIX Universal Markdown, the clipboard contents MUST contain the original markdown source for every structural element visible in the rendered display. A copy operation that drops, transforms, or summarizes structural elements is non-conformant.

5.2 Clipboard Format Requirements

When a copy operation produces multiple clipboard formats (e.g. text/plain, text/html, text/markdown):

• The text/plain format MUST contain a plain-text rendering with structural elements preserved (e.g. table content laid out in tab-delimited or aligned-text form).
• The text/markdown format, if present, MUST contain the AIX Universal Markdown source verbatim.
• The text/html format, if present, MUST be a faithful HTML rendering of the markdown source.

5.3 Element Preservation Tests

The following elements MUST survive a copy-paste round trip with no loss:

• Headings (all levels)
• Bulleted and numbered lists (all nesting levels)
• Tables (header row, alignment row, all data rows)
• Code blocks (with language identifier preserved)
• Inline code, emphasis (italic, bold, bold italic), links (text and URL)
• Section separators
• Citation markers and the Sources section

Any element that fails the round-trip test is a copy-layer conformance failure.

6. Validation Tests

A document claims AIX Universal Markdown conformance only if it passes all six tests. A tool implementing this specification (e.g. the AIX Validator) MUST report which tests fail and where.

6.1 The Six Tests

6.2 Conformance Levels

A document that passes Standard but fails Strict indicates a generator-conformant document hosted on a non-conformant interface; the failure surface is the interface, not the generator.

7. Canonical Worked Example

This section reproduces the AIX universal markdown test prompt and the canonical compliant response. A generator claiming AIX Universal Markdown conformance SHOULD produce output substantively identical in formatting to this canonical response when given this prompt.

7.1 The Universal Test Prompt

Give me an overview of the top 5 AI agent platforms in 2026.
For each one, include a paragraph description, a bullet list of key features,
and summarize all five in a comparison table showing: platform name,
open source (yes/no), self-hosted (yes/no), primary use case, and pricing model.

This prompt is the AIX Universal Markdown conformance test prompt. It reliably elicits the three core markdown structural elements — paragraphs, bullet lists, and tables — in a single response, making it suitable as a baseline conformance check.

7.2 The Canonical Response

# Top 5 AI Agent Platforms in 2026

## 1. LangGraph

LangGraph is the production-grade framework for stateful, durable, multi-step
agent workflows. Built by the LangChain team, it models agent execution as a
directed graph with explicit state transitions, making it the right choice
for teams that want full architectural control rather than a black-box
abstraction.

### Key features

- Graph-based orchestration with explicit state transitions
- Durable execution windows measured in hours
- Human-in-the-loop checkpointing at any node
- Python and JavaScript / TypeScript support
- LangSmith observability integration

## 2. CrewAI

CrewAI is a multi-agent orchestration platform organized around the metaphor
of crews — teams of agents with defined roles, goals, and tools collaborating
on shared objectives.

### Key features

- Role-based agent design with autonomous task delegation
- Open-source Python framework with optional commercial platform
- 100-plus built-in tool integrations
- Visual editor and code-first APIs

## Comparison

| Platform | Open source | Self-hosted | Primary use case | Pricing model |
| --- | --- | --- | --- | --- |
| LangGraph | Yes | Yes | Stateful production agent orchestration | Free framework, paid platform |
| CrewAI | Yes | Yes | Multi-agent team workflows | Free framework, paid platform |
| Microsoft Agent Framework | Yes | Yes | Enterprise agents on Microsoft and Azure | Free framework, infrastructure costs |
| Amazon Bedrock AgentCore | No | No | Framework-agnostic managed agent runtime | AWS usage-based |
| OpenAI AgentKit | No | No | OpenAI-native agent products | OpenAI API usage |

## Summary

For full architectural control over stateful agents, choose LangGraph.
For business-readable multi-agent teams, choose CrewAI.
For Microsoft and Azure environments, choose Microsoft Agent Framework.
For framework-agnostic managed runtime, choose Amazon Bedrock AgentCore.
For OpenAI-native deployments, choose AgentKit.

A generator that produces output substantively conforming to this canonical response across all 17 generator rules passes AIX Universal Markdown Basic and Standard. Strict conformance additionally requires the response to survive a copy-paste round trip through the hosting interface with no structural loss.

8. Governance & Versioning

8.1 Versioning Policy

8.2 Amendment Process

To propose a new rule:

1. Document the empirical variance the rule resolves (e.g. observed in N out of M tested generators).
2. Specify the canonical form, the rationale, and a compliant example.
3. Define the validation test that detects non-conformance.
4. Submit for ratification via the AIX governance process (see AIX 2.2 §11.4).

8.3 Relationship to AIX

AIX Universal Markdown is a companion specification to AIX 2.2. Conformance to AIX Universal Markdown is OPTIONAL for AIX 2.2 tools that do not emit markdown.

AIX 2.2 tools that emit markdown output (e.g. the content_authoring task type, §8.1 of AIX 2.2) SHOULD declare AIX Universal Markdown conformance via the meta object:

"meta": {
  "aixUniversalMarkdown": {
    "version": "0.1",
    "conformanceLevel": "standard"
  }
}

Graduated requirement notice: In AIX Universal Markdown v1.0, this requirement will be upgraded from SHOULD to MUST. AIX 2.2 tools currently emitting markdown should plan to declare conformance during the v0.x → v1.0 transition. The formal upgrade announcement will accompany v0.2 of this specification, giving the community at least one minor-version release cycle to adapt before the requirement becomes binding.

9. Conformance Testing Methodology (Non-normative Appendix)

This appendix codifies the methodological discipline required to produce credible AIX Universal Markdown conformance evidence. It is non-normative: it places obligations on testers and ratifiers, not on generators or interfaces.

9.1 Raw-Capture Rule

All conformance test data MUST be captured at the model output layer — directly from the chatbot’s raw clipboard copy, raw API response, or equivalent unprocessed source — and MUST NOT pass through any intermediate notes app, document editor, or clipboard manager before reaching the Validator.

This rule disciplines the testing pipeline. It does not impose new requirements on generators, interfaces, or copy/export layers.

9.2 Bear, a Class Example

In May 2026, controlled experiments routed identical chatbot outputs through Bear (a respected notes app) before reaching the Validator. Two distinct mutation classes were observed:

• Structural mutation (Gemini). Bear converted asterisk bullets to hyphens (bypassing the Bullet Marker rule entirely) and dropped a comparison table from the clipboard during the paste cycle. The Validator reported 1 issue against a raw-capture baseline of 36 — a 35-issue under-report driven entirely by Bear’s normalization behavior.
• Character-level mutation (Perplexity). Bear normalized approximately 15 of the U+2011 non-breaking hyphens to U+002D ASCII hyphens during the paste cycle. The Validator’s bucket FAIL count stayed at 2 of 6, but the depth dropped from 65 issues to 50 — a 15-issue under-report invisible at the summary-test level.

The mutation class is not unique to Bear. Notion converts pasted markdown to its own block format and surfaces a re-derivation on copy out; Google Docs flattens to a proprietary structure; Obsidian preserves more than most but still applies its own normalization; and macOS Pasteboard performs conversions when applications declare multiple representations of the same selection. Any tool between the generator’s output buffer and the Validator’s input buffer is a potential fidelity-loss surface. The case study at solotrillion.io/markdown-wars documents the Bear case in full.

9.3 Direct-Paste Evidence Threshold

A claimed conformance gap qualifies for inclusion in the AIX Universal Markdown changelog or amendment process if and only if:

1. The gap was reproduced via a direct-paste test of the specific generator output (no intermediate tools in the capture pipeline).
2. The test run is dated.
3. The Validator output is recorded in the spec corpus or in a versioned provenance ledger.

Gaps observed only in laundered test data (via Bear, Notion, Google Docs, or any other intermediate tool) are evidence of the intermediate tool’s behavior, not of the generator’s behavior. They MAY be cited as case-study material — see §9.2 for the canonical example — but MUST NOT serve as the basis for tightening normative rules against generators.

9.4 Provenance Ledger

The amendment process for v0.2 and subsequent versions maintains a provenance ledger recording every test run, its capture pipeline (raw vs intermediate-mediated), its date, and its Validator output. The ledger is a governance artifact, not a normative requirement. Its purpose is to make the chain of custody for every cited gap auditable by spec implementors, chatbot vendors, and the broader community.

10. Changelog

Version 0.1.3 — May 28, 2026

Patch revision. Editorial corrections, family-site alignment, no semantic changes.

Bear identified correctly as a notes app. Earlier drafts (v0.1.2) described Bear as a “writing app” — corrected in §9.1 (the raw-capture rule’s enumerated tool classes now read “notes app, document editor, or clipboard manager”) and §9.2 (Bear introduced as “a respected notes app”). §9.2 retitled from “Why Intermediate Tools Invalidate Test Data — The Bear Problem” to “Bear, a Class Example.”

Editorial pass. Removed “silently” and “quietly” constructions from §4 normative prose (Lossless Rendering and Markdown Identity Preservation reworded to keep MUST/MUST NOT teeth without the adverb) and from §9 throughout. Minimized leading “the” in subheads. No normative effect.

solotrillion.io reference site brought into alignment with Ubertrends LLC family-site standards (footer Ubertrends Network expanded to canonical seven-site list, canonical copyright line adopted). Does not affect the spec itself — recorded here for the joint deploy.

Version 0.1.2 — May 26, 2026

Patch revision codifying conformance testing methodology.

§9 Conformance Testing Methodology added (non-normative appendix). Specifies the raw-capture rule for test data, documents Bear as the evidence basis (May 2026 experiments showing structural and character-level mutation when chatbot output passes through an intermediate notes app or document editor), defines the direct-paste evidence threshold for cited gaps, and references the public provenance ledger. The appendix is non-normative — it places obligations on testers and ratifiers, not on generators or interfaces. The original §9 Changelog renumbers to §10.

No semantic changes to generator rules, validation tests, or conformance levels.

Version 0.1.1 — May 26, 2026

Patch revision incorporating early review feedback. Two amendments:

§3.2 restructured. The nesting case (where an enumeration sits inside an existing H2 section) was previously buried in the prohibitions paragraph. It is now a first-class clause of the rule, with three explicit nesting levels (document root → H2, under H2 → H3, deeper → continue one level below parent). The rule’s behavior is unchanged; only its readability is improved.

§8.3 amended. Clarified the conformance requirement for AIX 2.2 tools that emit markdown. The original OPTIONAL/SHOULD language is preserved; a graduated requirement notice has been added pre-announcing that §8.3 will be upgraded from SHOULD to MUST at v1.0. The formal upgrade announcement will accompany v0.2. Tools currently shipping markdown output should plan accordingly.

Version 0.1 — May 2026

Initial draft. Specifies 17 generator rules across heading hierarchy, lists, tables, separators, emphasis, code, special characters, and citations. Defines the three-layer model (model output, interface render, copy/export). Specifies six validation tests and three conformance levels. Includes canonical worked example.

This is a public draft for review. Issues, proposals, and amendments welcome via the AIX governance process.