Typed Structure Over Flat Text
Why AI Agents Need Traversable Documents
You are reading a typed document. Every block on this page has a declared type —
::summary, ::callout, ::data, ::code, ::decision. An AI agent reading
this page knows what each block IS without guessing. On a Markdown page, it
would have to infer all of that from visual formatting. The medium is the message.
AI agents operating on flat text waste tokens, hallucinate structure, and cannot perform budget-constrained navigation of knowledge hierarchies. Typed document formats — where block types, relationships, and token costs are declared, not inferred — are an architectural prerequisite for efficient AI agent operation. We prove this with HBDS (Hierarchical Budget-Constrained Descent Search), a traversal algorithm that is impossible on flat text and trivial on typed documents. The format is not a style preference. It is a capability gate.
The Problem: Flat Text Is the Default
AI agents — coding assistants, research tools, knowledge workers — consume documents constantly. Every agent-document interaction follows the same loop: read text, extract meaning, act. The dominant medium for this loop is flat text: Markdown, HTML, plain prose.
This is treated as a given. It shouldn't be.
Flat text forces agents to infer structure that could have been declared. Every inference is a potential hallucination. Every missing type boundary is a parsing ambiguity. But the deeper problem is not efficiency — it is capability. Certain algorithms that would make agents dramatically more effective are impossible on flat text, because the format lacks the information the algorithm requires.
| What Flat Text Lacks | What Goes Wrong | Example |
|---|---|---|
| Block types | Agent guesses what a paragraph means | Is this code block an example, a requirement, or a test case? |
| Typed cross-references | Agent cannot build a knowledge graph | `[see auth doc](./auth.md)` — what's the relationship? |
| Priority signals | Agent reads everything equally | Boilerplate gets the same attention as critical decisions |
| Pre-computed token costs | Agent cannot plan its reading | "How many tokens will this subtree cost?" — unknowable |
Context Limits Are Permanent
A common response: "Context windows are getting bigger — this problem goes away."
It doesn't. Context windows are growing (4K to 128K to 200K to 1M). But the knowledge worth querying grows faster. The internet has trillions of tokens. A company's knowledge base has millions. Even a 10M context window is finite against an effectively infinite corpus.
| Constraint | Cause | Can It Be Eliminated? |
|---|---|---|
| O(n^2) attention | Every token attends to every other token | No — sparse attention trades coherence for length |
| KV cache memory | Key-value pairs stored per token; 70B model at 128K = 20-40GB VRAM | Reduces constant, not scaling |
| Cost | Every context token costs compute on every forward pass | Reduces price, not the constraint |
| Lost in the middle | Accuracy degrades for information in middle of long contexts | Fundamental — more context can *hurt* |
Every 10x increase in context window is met by a 100x increase in available knowledge. The ratio gets worse, not better. Structure is the only way out.
The question is not "when will context windows be big enough?" The answer is never, relative to what exists. The real question is: how do you navigate knowledge within a finite budget?
That is a search problem, not a scaling problem. That is HBDS.
Alternative Architectures Make It Worse
Three architectural families attempt to escape the transformer's constraints. None succeed. All converge on the same conclusion: they need typed structure more than transformers do.
State Space Models (Mamba, RWKV)
Process tokens sequentially with fixed-size hidden state. O(n) time, O(1)
memory. The state IS the context — but it is lossy. The compression is uniform:
every token is compressed equally. But not all tokens are equally important. A
::decision block matters more than a ::callout[type=tip]. Without typed
structure, the SSM has no signal for what to preserve.
Typed structure tells the model what to remember.
Sparse Attention (Longformer, BigBird)
Reduce attention from O(n^2) to O(n) by restricting which tokens attend to
which. The agent must decide which tokens get global attention. In flat text,
this decision is arbitrary. In typed documents, the decision is semantic:
::summary blocks get global attention, ::callout[type=tip] blocks get
local only.
Typed structure tells the model where to look.
Memory-Augmented Models
Decouple the context window from external memory. But the read/write operations require addressing — the model must decide where to read from. In flat memory, addressing is by position (fragile) or by content similarity (embedding lookup). In typed memory, addressing is by type and hierarchy.
Typed structure tells the model how to navigate.
You do not escape typed structure by escaping the context limit. You make typed structure more important, because the new architectures have less room for error in their information selection. The flat-text tax gets worse, not better, as architectures become more sophisticated.
Five Failure Modes of Flat Text
When AI agents operate on untyped text, five systematic failures emerge.
F1: Structure Hallucination
The agent infers section boundaries or block purposes the author did not intend. A list under "Future Work" gets treated as current requirements. Flat text provides no machine-readable signal for "this is speculative" vs "this is a requirement."
F2: Type Ambiguity
A code block in Markdown could be an example, a requirement, a template, or a
test case. A blockquote could be a citation, a warning, or a definition. The
agent guesses. In a typed format, ::callout[type=warning] vs
::code[title="Example"] eliminates the ambiguity at parse time.
F3: Broken Traversal
Flat text cross-references are strings. The agent must resolve paths, hope files exist, parse from scratch, and infer how documents relate. No declared relationship types. No traversable knowledge graph.
F4: Context Budget Waste
Flat text has no priority signals and no pre-computed token counts. Every paragraph looks equally important. Agents cannot distinguish high-value content from boilerplate. Worse: they cannot plan their reading.
F5: Semantic Lossy Compression
When an agent summarizes to fit its context window, it compresses by position —
not by meaning. A typed document enables structured compression: keep
::decision and ::data blocks, drop ::callout[type=tip] blocks.
| Failure Mode | Missing Property | What Happens |
|---|---|---|
| Structure hallucination | Declared block types (P1) | Agent invents structure |
| Type ambiguity | Declared block types (P1) | Agent misclassifies content |
| Broken traversal | Typed cross-references (P2) | Agent cannot build knowledge graph |
| Context budget waste | Priority (P3) + Token costs (P4) | Agent reads blindly, overruns budget |
| Semantic lossy compression | P1 + P3 | Agent compresses by position, not meaning |
Typed Traversability: Four Properties
A document is "typed-traversable" when it has four properties. Each is a prerequisite for budget-constrained search.
| Property | What It Means | What It Enables |
|---|---|---|
| P1: Declared Block Types | Every block has a machine-readable type | Semantic relevance scoring, type-based compression |
| P2: Typed Cross-References | Links carry relationship semantics | Hierarchical traversal, knowledge graph construction |
| P3: Priority Signals | Documents declare importance relative to budget | Budget-aware reading order, graceful degradation |
| P4: Pre-Computed Token Costs | Every node exposes its token cost before reading | Budget planning, pre-read verification |
The Traversability Spectrum
| Level | Format | Properties | Search Capability |
|---|---|---|---|
| 0 | .txt | None | None |
| 1 | .md | Heading hierarchy (implicit) | None |
| 2 | .md + YAML frontmatter | P3 (partial) | Classification only |
| 3 | ARDS v3 (.context/) | P2 + P3 | Classification + partial navigation |
| 4 | Typed format (.surf) | P1 + P2 + P3 | Classification + navigation + synthesis |
| 5 | Typed + schema + token costs | P1 + P2 + P3 + P4 | Full budget-constrained search (HBDS) |
Each level adds a property. Each property unlocks an algorithmic capability. The key insight: the algorithm tells you what the format needs.
The marginal benefit for humans diminishes at each step. The marginal benefit for AI agents increases. The crossover — where the next step benefits AI more than humans — is between levels 2 and 3. Everything above level 2 is primarily for machines.
What About Structured Data Formats?
The argument so far has compared typed documents to flat text. A reasonable objection: "I don't use flat text — I use JSON. My data is already structured."
This conflates two different things. JSON is a serialization format. SurfDoc is a document model. They solve different problems at different layers. JSON gives you syntax — nesting, arrays, key-value pairs. It does not give you semantics — block types, traversal relationships, budget metadata, or summary fallback hierarchies.
The distinction matters because HBDS does not require structure. It requires typed traversable structure with pre-computed costs. JSON has the first word. It lacks the last four.
Testing JSON Against the Four Properties
| Property | JSON | JSON Schema | JSON-LD | SurfDoc |
|---|---|---|---|---|
| P1: Declared block types | No — keys are arbitrary strings, not semantic types | Partial — validates shapes, not document semantics | No — describes entity relationships, not block types | Yes — `::decision`, `::data`, `::summary` are parsed types |
| P2: Typed cross-references | No — `$ref` is a pointer, not a semantic relationship | No — validates structure, does not describe relationships | Yes — `@type` and `@context` carry semantics | Yes — links carry relationship types |
| P3: Priority signals | No — every key is equally important | No — required/optional is validation, not priority | No — no importance hierarchy | Yes — block types encode priority (`::decision` > `::callout`) |
| P4: Pre-computed token costs | No | No | No | Yes — every node exposes cost before reading |
JSON has zero of the four properties. JSON Schema adds partial P1 (it validates
shapes, but "type": "string" is not a document-semantic type — it cannot tell
an agent whether a string is a decision, a summary, or a warning). JSON-LD adds
P2 through linked data semantics, but lacks P1, P3, and P4.
Where Structured Data Lands on the Spectrum
| Level | Format | Properties | Search Capability |
|---|---|---|---|
| 0 | .txt | None | None |
| 1 | .md, JSON, YAML, TOML | Implicit hierarchy | None |
| 1.5 | JSON Schema | Partial P1 (validation types) | None |
| 2 | .md + YAML frontmatter, JSON-LD | P2 (partial) or P3 (partial) | Classification only |
| 3 | ARDS v3 (.context/) | P2 + P3 | Classification + partial navigation |
| 4 | Typed format (.surf) | P1 + P2 + P3 | Classification + navigation + synthesis |
| 5 | Typed + schema + token costs | P1 + P2 + P3 + P4 | Full HBDS |
JSON lands at Level 1 — the same level as Markdown. This surprises JSON users because JSON feels more structured. It is. But the structure it provides (nesting, arrays, data types) is serialization structure, not document structure. Markdown's heading hierarchy and JSON's nesting both give you implicit organization. Neither gives you declared block types, priority signals, or token costs.
Serialization structure answers: "How is this data shaped?" Document structure answers: "What does this content mean, how important is it, how much will it cost to read, and what is it related to?" JSON answers the first question. HBDS requires answers to all four.
"I'll Just Add Those Properties to JSON"
You can. Add a "block_type" field to every object. Add "token_cost" and
"priority" fields. Define a "refs" array with typed relationships. Use
JSON Schema to validate the structure.
At that point you have invented a typed document format that uses JSON syntax. You have built SurfDoc with curly braces. The question is whether the result is better or worse for the dual audience — humans who author and AI agents who traverse.
| Dimension | JSON + custom schema | SurfDoc |
|---|---|---|
| Human authoring | Verbose — closing braces, quoted keys, no prose flow | Prose-native — write text, add `::type` when needed |
| Syntax errors | One missing comma breaks the entire document | Block-level — one malformed block does not affect others |
| Readability | Data-oriented — optimized for machines | Document-oriented — optimized for reading |
| Diff quality | Structural changes obscured by syntax noise | Clean diffs — content changes are visible |
| Tooling | Universal parsers, editors, validators | Purpose-built parser (surf-parse), growing ecosystem |
| AI traversal | Identical — both provide P1-P4 if schema is complete | Identical — both provide P1-P4 |
The last row is the point. If both formats provide P1-P4, HBDS works equally well on either. The algorithm does not care about syntax. It cares about properties. The argument for SurfDoc over JSON-with-schema is not algorithmic — it is ergonomic. Humans write documents, not data structures. A format designed for documents will always be more natural for the authoring side of the dual audience.
JSON is a serialization format. HBDS requires a document model. You can serialize the model as JSON — but you still need the model, and humans still need to write in it.
HBDS: The Proof by Construction
If typed structure is merely a preference, then flat text should support the same algorithms. It doesn't. HBDS (Hierarchical Budget-Constrained Descent Search) is a search algorithm that navigates typed knowledge hierarchies under strict token budgets. It operates in four phases — ORIENT, DESCEND, SYNTHESIZE, WRITE BACK — each consuming tokens from a monotonically decreasing budget.
Every phase maps to a format property. Every property maps to a gap in flat text.
| HBDS Phase | Required Property | What Flat Text Lacks |
|---|---|---|
| ORIENT | P2: Typed cross-references | No hierarchy — headings are visual, not structural |
| DESCEND (scoring) | P1: Declared block types | No types — agent guesses what content means |
| DESCEND (budgeting) | P4: Token costs | No token counts — must read to know the cost |
| DESCEND (degradation) | P1 + P3: Types + priority | No summary vs. content distinction |
| SYNTHESIZE | P1: Block types | No type-aware merging or deduplication |
| WRITE BACK | P2: Typed references | No insertion semantics in flat text |
HBDS requires P1-P4. Flat text provides none. Therefore flat text cannot support HBDS. The format is a capability gate, not a style preference.
HBDS: How AI Agents Search Typed Documents — the complete four-phase walkthrough with code, budget model, beam search examples, trust scoring, and configuration reference.
Implications
For AI Agent Builders
Agents that can consume typed ASTs — routing ::decision blocks to a decision
tracker, ::data blocks to a schema generator — are architecturally superior to
agents that receive undifferentiated prose. Agents that can run HBDS on typed
knowledge hierarchies can do things that flat-text agents structurally cannot.
For Document Format Designers
The audience for document formats has expanded from one (humans) to two (humans
- AI agents). New formats must be dual-audience: writable by humans, algorithmically navigable by machines.
For Knowledge Base Platforms
A platform that stores content in a typed, open, traversable format becomes an AI-native knowledge base without any adapter layer. The format IS the API.
For the RAG Community
HBDS may be a replacement for RAG on typed corpora, not just an improvement. RAG retrieves flat fragments by similarity. HBDS navigates a typed hierarchy by semantic descent. If the corpus is typed, HBDS is strictly more capable.
Conclusion
The document format is not a cosmetic choice for AI-agent systems — it is an architectural one that determines which algorithms are available.
When the structure is declared, not inferred, agents are more accurate, more efficient, and more complete — and they can run algorithms that flat-text agents structurally cannot.
The era of flat text as the default medium for AI-agent consumption is ending. What replaces it is typed, traversable, budget-aware structure — designed not for how humans read, but for how algorithms search.