The Graceful Truth Layer: Why Every SiteNexis API Response Has a State
Raw JSON responses fail silently. The GTL pattern wraps every API response in a state envelope — complete, partial, or empty — so every UI component knows exactly what it is rendering and why, even when data is missing or partially available.
Most APIs return data or an error. When data is partially available — some agents completed, others failed — the typical response is either to return incomplete data without signaling incompleteness, or to fail the entire request. Neither is acceptable when an audit takes 3–8 minutes and involves 16 parallel agents, any of which may fail independently. The Graceful Truth Layer solves this with a three-state envelope that every SiteNexis API route returns.
The Envelope Structure
Every GTL response has the same shape: state (complete | partial | empty), timestamp (when the response was generated), data (the actual result, or null), and an optional reason string (explaining why the state is partial or empty). State complete means the full result is available. State partial means the result is available but some components are missing — the reason field explains what is absent and why. State empty means no data exists yet — the audit has not completed, the agent was skipped for this plan tier, or there is no previous audit to compute a delta from.
●The GTL pattern originated from a practical problem: the Temporal Authority Agent can only compute velocity and drift on the second and subsequent audits. On first audit, the response is not an error — it is a legitimate "baseline established" state. Without GTL, the frontend would receive null data and have no way to distinguish "no data yet" from "analysis failed."
How Partial States Work
Partial state is common in Layer 4 analysis. The Machine Trust Agent computes five sub-scores. If the Claude API fails during contradiction detection, the agent continues with the remaining four sub-scores, sets contradictionAbsenceScore to null, and completes. The API route returns state: partial with reason: "Contradiction detection unavailable — API timeout." The dashboard renders the four available sub-scores and shows a distinct UI for the missing one — not an error, not missing data, but an explicit partial result with context.
Dashboard Component Behavior
Every dashboard page that fetches sub-report data via the useAuditSubReport hook reads the GTL state before deciding what to render. State complete: render the full result. State partial: render available data with a partial indicator and the reason string. State empty: render a specific empty state — either "audit still processing," "feature not available on your plan," or "baseline being established." This eliminates all silent data failures from the UI.
Why Not Just HTTP Status Codes?
HTTP status codes capture request-level success or failure — 200, 404, 500. They do not capture data-level completeness. A 200 response can contain a perfect result or a result missing three of five components. GTL operates at the data level, inside the response body, providing semantic information about the completeness and freshness of the data returned. The HTTP status code and GTL state are complementary, not redundant.
Every SiteNexis API route and dashboard uses GTL. See it in your own audit.
Start free audit