Hyphae Atlas: An Agent That Won’t Call a Database Migration Safe Without Receipts

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content What I Built Hyphae Atlas is an evidence agent that answers a deliberately difficult class of engineering question: is this migration, capability statement, or product claim actually supported for the exact release and environment being discussed? The subject is Hyphae, a local-first data engine. Its public documentation includes release receipts, normative specifications, machine-readable contracts, compatibility fixtures, benchmark gates, current product guidance, historical plans, and unreleased work. Those sources are individually useful, but a keyword match across them is not enough. A fluent answer can still be wrong if it silently mixes releases, treats a historical target as current status, or promotes an unreleased contract to a shipped feature. Atlas turns that documentation into three focused workflows: - Migration Advisor checks upgrade and import paths, required steps, compatibility boundaries, and explicit non-guarantees. - Capability Inspector verifies whether a capability exists for the named release and surface, including protocol and environment qualifiers. - Claim Auditor tests public wording against authoritative evidence and classifies it as supported, conditional, prohibited, or unproven. Each response is a structured report rather than a chat paragraph. It contains a verdict, applicability, findings, qualifiers, conflicts, limitations, recommended actions, and an evidence ledger. Every finding must resolve to content actually retrieved from Sanity Context before Atlas will expose an upstream link. The interface is available in English and Spanish, including generated reports. It includes guided examples, term-level tooltips, an operational MCP trace, an interactive conflict timeline, an Evaluation Lab, and a Three.js/GSAP graph showing the real flow from sources to the Sanity Knowledge Base, Context MCP, configured model, and verdict. Long-running live requests display the current agent stage instead of an unexplained spinner. There are also six immediate replays: migration, capability, and claim audits in both languages. These are preserved live Context runs, not hand-written sample answers. Each replay retains its capture time, retrieved Knowledge Base paths, four-stage trace, report, and resolved source provenance. Visitors can inspect those without spending model budget, then choose a fresh live query if they want to exercise the complete path. Hyphae and its source documentation existed before this challenge. For the challenge, I built the Sanity content model, deterministic ingestion pipeline, authority and lifecycle policy, Knowledge Base, backend-owned MCP agent loop, evidence resolver, bilingual application, replay system, evaluation corpus, Cloudflare deployment, and abuse controls. Demo Live application: atlas.terrizoaguimor.dev A useful first route through the demo is: - Open the Native 2.x to 3.0 migration replay and inspect why the answer separates supported import behavior from guarantees the sources do not make. - Open the G7 claim replay and compare the historical target, current gate status, and scoped 3.0.0 release receipt. - Use Proof Path on any finding to follow its Knowledge Base citation to a commit-pinned source with digest and lifecycle metadata. - Run Verify SHA-256 to compare the imported digest with bytes fetched from the allowlisted upstream repository. - Open the Evaluation Lab to inspect the final 12-case baseline and its acceptance criteria. Fresh live queries use the hosted xAI/Grok 4.6 synthesis provider and require a managed Turnstile check. The six evidence-rich replays remain immediate and challenge-free. Code Repository: github.com/terrizoaguimor/hyphae-atlas The repository includes: - all seven Sanity schema types; - the closed-world source manifest and idempotent importer; - the backend-owned Sanity Context client and provider adapters; - strict report-schema and citation-grounding validation; - the deterministic evidence resolver and SHA-256 verification endpoint; - the bilingual Next.js interface and replay data; - 12 gold evaluation cases and the audited baseline summary; - security smoke tests and a clean-room Cloudflare deployment script. The implementation paths that best explain the agent are src/agent/context-client.ts , src/agent/provider-agent.ts , src/agent/evidence-resolver.ts , and src/app/api/agent/route.ts . The corpus and final evaluation are reproducible from the scripts documented in the repository. How I Used Sanity Sanity is not a passive CMS in this project. It is the structured evidence layer that makes the verdicts possible. A content model for authority, applicability, and provenance I modeled seven related document types: - Source documents store repository path, source commit, SHA-256 digest, license, lifecycle, authority domains, and version scope. - Hyphae releases identify concrete release boundaries. - Capabilities describe support with explicit applicability. - Compatibility rules encode supported transitions and constraints. - Product claims preserve canonical claims and non-claims. - Evidence artifacts represent gates, fixtures, and release evidence. - Public contracts capture API and MCP surfaces. The imported corpus contains 20 curated public source documents and 13 additional structured records, for 33 namespaced Atlas documents in the production dataset. The sources cover claim language, the Native capability matrix, SQL and MVCC contracts, directory migration semantics, the Native MCP contract, access control, compatibility fixtures, current gate status, and the exact Hyphae 3.0.0 publication receipt. The importer uses deterministic hyphaeAtlas.* IDs, commit-pinned source URLs, SHA-256 content digests, and idempotent upserts. It also records the non-Atlas document count before and after import so that a corpus refresh cannot silently replace unrelated content. A repeated import produced the same IDs and totals. A Sanity Context Knowledge Base with an explicit job I built the Hyphae Atlas Knowledge Base with this purpose: Help Hyphae users, maintainers, and auditors determine whether a migration, capability, or technical claim is valid for an exact release, protocol surface, and evidence scope. The build generated 21 Knowledge Base entries from the 33 Atlas documents. Atlas uses both required Knowledge Base-mode tools: - initial_context reads the generated outline. - knowledge_base_read retrieves the smallest sufficient set of relevant entries, batching related evidence where possible. The authority policy is as important as retrieval. Atlas distinguishes published, historical, and unreleased material; prefers current gate records for gate status; uses release receipts for what a release actually proves; uses machine contracts for API behavior; preserves benchmark environment and commit qualifiers; and returns unknown or unproven when the evidence cannot support a safe affirmative answer. The provider-agnostic agent loop Atlas owns the MCP workflow on the server instead of delegating it to a provider-specific remote connector: - The backend calls initial_context . - The configured model selects between one and eight relevant outline paths. - Atlas rejects any selected path that is not present in that live outline. - The backend calls knowledge_base_read for the validated paths. - The model receives those retrieved entries and produces a schema-constrained report. - Atlas checks every finding citation against the exact retrieved text, then resolves trusted provenance through Sanity relationships. This boundary keeps the Sanity Context credential away from the model provider and makes the tool trace consistent across adapters. Atlas supports xAI, OpenAI, Anthropic, and HTTPS OpenAI-compatible APIs. The hosted demo and final live 12-case baseline use xAI/Grok 4.6. The other adapters passed mocked authentication, transport, and payload smoke tests; I am not presenting those as live-provider evaluations. Proof Path: citation to immutable upstream evidence A Knowledge Base citation may be an internal label such as Native gate status - Dataset . That label alone should not become a clickable source. After synthesis, the deterministic Evidence Resolver requires the citation to have appeared in the actual knowledge_base_read output. It then follows the known Knowledge Base entry and Sanity document relationships to the canonical sourceDocument . Only resolver-owned URLs are rendered. Model-provided URLs never become links. The resulting evidence row exposes: - the original public GitHub path; - the exact imported commit; - expected SHA-256 digest; - source license; - lifecycle state; - authority rank and applicability. The Verify SHA-256 endpoint accepts a namespaced Sanity source ID, reloads trusted provenance from Sanity, constructs an allowlisted raw.githubusercontent.com/Hyphae-Research-Foundation/hyphae URL, downloads a bounded response, and compares the bytes with the imported digest. Verification of docs/gates/native-gate-status.md matched byte for byte. A regression case using a forged https://example.invalid/README.md citation resolves to nothing. A visible trace without pretending schema validation proves truth Every report exposes a four-stage operational trace: - initial_context - orient on the live Knowledge Base outline. - knowledge_base_read - show the exact generated entry paths retrieved. - evidence_resolver - map grounded citations to canonical source records. - schema_validation - validate the JSON contract and required source resolution. This is an audit trace, not private chain of thought. The fourth stage confirms structural and grounding rules; it is not independent factual validation of the verdict. The Conflict That Changed the Authority Policy The most useful failure was a real temporal disagreement around Hyphae's G7 performance gate. The historical document docs/performance/microsecond-first.md s