{"path":"research/agent-readable-graph-architecture.md","content":"# Agent-Readable Graph Architecture\n\n**Date**: 2026-07-05 (research + design); persisted 2026-07-06\n**Status**: Shipped — this is the research and design reasoning that `deliberus/agent_readable.py` references. Deployed to production 2026-07-06.\n**Related**: [deliberus-as-alignment-infrastructure.md](deliberus-as-alignment-infrastructure.md) §6.6, [convergence.md](../convergence.md)\n\n> **This doc is the surface; the strategy came later.** What agents should be *served* was designed here in July. What it means for agents to be a **consumer class** — the reasoning-verification framing, the agent-side falsifier, the authority risk that gates it, an MCP tool set, and the reciprocity problem — was collected 2026-08-17 into [agents-as-a-consumer-class.md](agents-as-a-consumer-class.md).\n\n---\n\n## The problem: a legibility platform that AI minds can't read\n\nDeliberus exists to make reasoning legible — to minds, including AI minds. Yet deliberus.com was a client-rendered SvelteKit SPA (`adapter-static`): any non-JS agent fetch of a human URL returned the empty `index.html` shell, not content. A platform for making reasoning legible that is itself illegible to the AI systems that are among its most important readers is a **live thesis-contradiction**. It was not hypothetical: it materially corrupted the project's own funder-research subagents, which had to analyze Deliberus from a search snippet + Wikipedia + an arXiv abstract instead of the real corpus (producing an over-flattened funding verdict that later needed correcting). It also directly contradicts the alignment-infrastructure case's own §6.6 requirement, *\"AI systems must be able to interface with the graph meaningfully.\"*\n\nThe fix was smaller than it looked. The **data layer already existed** — `/claims/{id}`, `/extractions/{id}`, `/concepts/{term}`, and `/api/docs/{path}` all serve structured JSON/markdown. The only gaps were (a) the *human* URLs (`/claim/{id}`) served the shell, and (b) zero discoverability. So the whole thing is a FastAPI-layer addition: **no SSR, no adapter migration, no new runtime process.**\n\n## Decision 1 — Content negotiation on `Accept`, never User-Agent sniffing\n\nThe 2026 consensus (Vercel, Cloudflare \"Markdown for Agents\", Checkly, Evil Martians) is that **HTTP content negotiation is the durable, standards-based way to serve agent-friendly content**: the same URL returns markdown or JSON when the client sends `Accept: text/markdown` / `application/json`, and HTML to a browser, declared with `Vary: Accept`. Checkly's analysis found **Claude Code and Cursor already send `Accept: text/markdown`** — precisely the agents that would dogfood the graph.\n\nThe cloaking distinction is settled and load-bearing: serving the *same content in a different format* keyed on what the client *asked for* (the `Accept` header) is 25-year-old HTTP and is **not cloaking** — \"nobody called your REST API cloaked for returning JSON\" (Evil Martians). Serving *different content* keyed on *who is asking* (User-Agent sniffing) **is** cloaking and Google penalizes it. So negotiation keys on `Accept`; explicit `.md`/`.json` suffix URLs cover agents that forget the header; User-Agent is used only for analytics and `robots.txt` allow-listing, never as the sole discriminator.\n\nGoogle's Mueller/Splitt raised one real caution — *parallel bot-only pages rot silently* (no user emails you when the markdown version breaks). That does not bite here because the machine surface is **generated from the same graph the SPA reads** (one source of truth, no hand-maintained copy), and a smoke test guards it. The honest inversion: the markdown/JSON is not a dumbed-down clone — it *is* the structured graph the SPA merely renders.\n\nMarkdown is the primary machine format (token-efficient, the format LLM agents parse most reliably, and what the target agents request); JSON is the structured format.\n\n## Decision 2 — Discoverability trio: `robots.txt`, `llms.txt`, `sitemap.xml`\n\n`llms.txt` is **agent-navigation infrastructure, not an SEO signal**. The 2026 data is blunt: ~5.9% of top sites have one, ~97% of files receive zero AI requests, and no major LLM fetches it at inference time (Ahrefs, Thunderbit, Originality.ai). But Originality.ai's conclusion is exactly this use case — *\"a clean map of a site's structure for autonomous agents before they begin a task\"* — and IDE agents (Cursor, Continue, Cline) plus MCP integrations do read it. Cost is ~30 minutes; ship it with no search-lift expectation. `robots.txt` is the actually-*enforced* lever (major AI crawlers respect named-UA rules), so it ships too and points at the sitemap. `sitemap.xml` enumerates the graph's human URLs.\n\n## Decision 3 — JSON in Deliberus's own vocabulary, deliberately NOT conformed to AIF\n\nThe obvious move would be to conform the JSON to AIF (the Argument Interchange Format), the academic argument-graph standard. **We deliberately do not**, because AIF's two founding premises fight Deliberus's most distinctive convictions:\n\n- **AIF reifies every scheme as an S-node** (information I-nodes may only connect *through* scheme nodes). Deliberus uses **one node type (Claim)** with the scheme carried on the edge — a deliberate unification AIF would re-fracture.\n- **AIF's I-node is an atom.** Deliberus's `DECOMPOSES_INTO` is a **part-whole / examinability relation**, not inference: a mother claim *is* its subclaims at higher resolution; the subclaims do not *infer* it. Encoding decomposition as AIF's RA-node (premises → conclusion) would assert a category error, and it has no representation for the \"currently-undecomposed, invitable-deeper\" status that is Deliberus's core (No Copout Axioms).\n\nTwo further Deliberus layers have no AIF home at all: the **contested-concept / sense layer** and the **maturity + honest-terminus layer** (draft→canonical; `dissolved` / `empirical` / `fittingness` / `structural` / `axiom_choice` / `permissive_zone`). Conforming would evict exactly the insights that differentiate the project.\n\nWe *do* share AIF's sound core — typed, scheme-classified relationships with Walton schemes and critical questions — and that independent overlap is **convergent validation, not a reason to conform**. An AIF/SADFace *export adapter* is a clean boundary add if interoperability is ever wanted; it is never a design constraint on the native representation and never leaks back into the core model. The native JSON therefore keeps **argument edges (`argues`/`argued_by`) and decomposition edges (`decomposes_into`/`part_of`) as separate first-class blocks**, precisely the distinction a generic standard would flatten.\n\n## What shipped (`deliberus/agent_readable.py` + `api.py`)\n\n- Content negotiation on `/claim/{id}` and `/extraction/{id}` (browser → SPA; `Accept: text/markdown|application/json` → clean content; `Vary: Accept`).\n- Explicit `/claim/{id}.md` + `.json`, `/extraction/{id}.md` + `.json`, `/concept/{term}.md` + `.json`.\n- `/robots.txt`, `/llms.txt`, `/sitemap.xml`; `Link: rel=\"alternate\"` header; `app.html` hint.\n- Native-vocabulary JSON serializer; markdown serializers for claim / extraction / concept. Later extended with a reader preamble (maps-not-endorses framing) and scrutiny state (the completeness verdict + terminus type) on every surface.\n- Anti-rot unit tests (the machine surface can break silently; a user won't email us).\n\n## Sources\n\nContent negotiation: [Vercel](https://vercel.com/blog/making-agent-friendly-pages-with-content-negotiation), [Cloudflare Markdown for Agents](https://blog.cloudflare.com/markdown-for-agents/), [Checkly](https://www.checklyhq.com/blog/state-of-ai-agent-content-negotation/), [Evil Martians](https://evilmartians.com/chronicles/how-to-make-your-website-visible-to-llms). Cloaking: [SearchEngineJournal on Mueller](https://www.searchenginejournal.com/cloudflares-new-markdown-for-ai-bots-what-you-need-to-know/567339/). llms.txt adoption: [Originality.ai via PPC Land](https://ppc.land/llms-txt-adoption-rises-8-8x-but-97-of-files-get-zero-ai-requests/), [Thunderbit/Searchless](https://searchless.ai/articles/2026-05-08-llms-txt-adoption-2026-data-real-adoption-rates/), [Tygart Media](https://tygartmedia.com/llms-txt-2026-spec-robots-txt-pairing-verification/). Argument standards: [AIF spec (arg-tech)](http://www.arg-tech.org/wp-content/uploads/2011/09/aif-spec.pdf), [SADFace](http://arg.napier.ac.uk/projects/sadface/), [schema.org ClaimReview](https://schema.org/ClaimReview).\n"}