Runtime State Is Queryable Directly, Not Through a Synthesized API

The eOS runtime platform exposes its own state to queries directly. An agent, a human, or another LLM that wants to know what objects exist, what their state is, or what events have fired queries the runtime itself rather than a separately-maintained data-model API. The runtime's state graph is the introspection surface, not a source the introspection layer is synthesized from; agents do not read a cached or synthesized view of state, they read the live state.

Why It Is Held

Introspection-API patterns built on top of the runtime fragment. Each team builds a separate API surface (REST endpoints, GraphQL schema, custom protocol) that mirrors a chosen subset of runtime state, each implementation has bugs the team rebuilds, and each accumulates synchronization drift between the API's view and the runtime's actual state. The application code that maintains "when state changes, update the introspection-API view" is not the application's actual logic -- it is bookkeeping the platform could provide. Treating runtime self-description as a primitive removes the synchronization layer entirely: the runtime exposes itself, and agents reading the introspection surface read the same state graph that every other primitive operates on.

The platform-as-introspection-surface stance composes with the persistent-state primitive ([[Runtime State Is Persistent by Default, Not by Application Discipline]]). The state graph the introspection primitive reads is the same state graph the persistence primitive maintains across restart -- there is no separate "persisted state" and "introspectable state" pair to keep in sync. An agent querying the runtime for an object's state at restart time observes the post-restoration state, not a synthesized snapshot built from external sources. Without runtime-level persistence, introspection would have to coordinate with whatever mechanism rebuilt state at startup -- exactly the synchronization-drift pattern the primitive removes.

The platform-as-introspection-surface stance composes with the capability-separation primitive ([[Capability Boundaries Are Runtime-Enforced, Not Policy-Checked]]). What introspection can see is bounded by the querying principal's capability tier -- a highly-privileged query observes the full state graph; an unprivileged agent's query observes only what its capability allows. The capability layer that bounds mutation also bounds observation, and the same enforcement machinery applies. Without runtime-level capability separation, an introspection endpoint would have to apply its own access control on top of the query path -- a separate enforcement layer that the platform's primitive makes redundant.

The eOS-kernellib foundation provides building blocks at the runtime layer: a status query returns runtime metadata about objects, programs, callouts, and resource usage, and a call-trace query returns the current call stack at any point. The kernel layer uses these internally for resource accounting but does not yet expose a public introspection endpoint -- the gap is a JSON/HTTP introspection layer for agent state and object registry, built as a translation surface over the runtime's own status and object-graph queries.

The Conviction is held because the no-synchronization-drift agent-coding experience is what platform adoption purchases for the introspection scenario. When the runtime is the introspection surface, agents trust that what they read is what is, without having to reason about whether the API view has caught up with the runtime's actual state. Trading the primitive for a synthesized API would surrender exactly the property that lets agents (and humans, and other LLMs) reason about runtime state with confidence rather than with reconciliation logic.

What It Asks

Honoring this Conviction asks the project to keep introspection on the runtime itself, not on a synthesized mirror.

The introspection surface reads the runtime's status and object graph directly, formats results for HTTP/JSON consumption, and applies capability-tier filtering inline. The layer is a translation surface for the runtime's state, not a synthesized data-model view that requires its own state.
Tests and demonstrations query runtime state directly, not through a synthesized cache. Runtime introspection is exercised at the smallest scale before it is exercised through any higher-level surface built on top of it.
Decisions introducing synthesized API mirrors must surface the cost. A Decision adding "for compatibility with external tooling, expose a synthesized GraphQL API mirroring agent state" or "for performance, cache introspection results in a separate query layer" reintroduces exactly the synchronization drift the primitive removes. Such Decisions weigh the integration or performance benefit against the platform-fit cost imposed on this Conviction.
Communication distinguishes runtime-direct introspection from synthesized-API patterns. When the project's state-introspection claim is communicated externally, the distinction between querying the runtime's actual state graph (runtime primitive) and querying a synthesized data-model API maintained by application code (application pattern) is the load-bearing detail. The two are sometimes conflated in agent-infrastructure copy that uses "observability" or "introspectable" loosely.
Workstream scoping checks the introspection layer for new agent capabilities. Workstreams adding capabilities that introduce new state shapes or new event categories ensure those shapes are queryable through the same runtime-introspection mechanism. New state that requires a separate query layer is operating outside the platform's primitive for that state.

Drift Recognition

The Conviction has weakened when the project's outputs treat introspection as a separate API surface that has to be maintained, rather than as direct runtime querying.

Synthesized API mirrors maintained alongside runtime state. When the codebase accumulates "update the introspection view when X mutates" patterns -- explicit save-to-API-cache calls, change-data-capture pipelines, materialized view refreshes -- the platform's primitive has been demoted to "one source the API mirrors". The mirror is the drift evidence; in a held-Conviction world, there is no mirror to maintain.
Introspection endpoints that lag runtime state. When operational documentation describes introspection as "may lag actual state by N seconds" or "eventually consistent with runtime state", the synchronization drift the primitive prevents is being acknowledged as a feature rather than corrected. The lag itself is the Conviction's drift signal.
External observability infrastructure as the introspection authority. Decisions routing in-runtime introspection through external observability platforms (Prometheus, OpenTelemetry, custom metrics pipelines) for in-runtime queries demote the platform from "the introspection surface" to "one telemetry source". External observability is defensible for cross-instance metrics or historical analytics; it is drift when applied to "what is the current state of this object" queries the runtime's primitive already answers.
Custom access control on the introspection surface. When the introspection layer applies its own access control (separate from the runtime's capability layer), the capability primitive's coverage of observation has been replaced. The two layers will drift; the duplicate enforcement is itself the Conviction-weakening pattern.
Cumulative drift across multiple sessions. If several consecutive rounds of work add features that quietly route in-runtime introspection through synthesized APIs, external observability platforms, or duplicate access-control layers without surfacing the platform-fit cost, the project has drifted from holding the Conviction.

Relations

conforms_to::[[Conviction Form Contract]]
- Exercises the Contract's Stance plus Why It Is Held plus What It Asks plus Drift Recognition body shape.
grounded_in::[[Agent Runtimes Require Native Primitives, Not External Glue]]
- The state-introspection primitive is one instance of the broader stance that what is normally a pattern (custom introspection APIs, change-data-capture pipelines, materialized views, external observability platforms) becomes a primitive in the runtime that every line of agent code can rely on; external observability patterns cannot deliver platform-level direct query of the runtime's own state graph. Currently a ghost link; the diagnostic Conviction has not yet migrated.
grounded_in::[[Runtime State Is Persistent by Default, Not by Application Discipline]]
- State introspection matters because the queryable surface IS the persistent state graph: there is no separate "live state" the introspection layer must catch up to, because the state a query returns and the state the runtime persists are the same durable image.
composes_with::[[Runtime State Is Persistent by Default, Not by Application Discipline]]
- State introspection and persistence reinforce each other: the state graph the introspection primitive reads is the same state graph the persistence primitive maintains across restart -- there is no separate "persisted state" and "introspectable state" pair to keep in sync. Without runtime-level persistence, introspection would have to coordinate with whatever mechanism rebuilt state at startup -- the synchronization-drift pattern the primitive removes.
composes_with::[[Capability Boundaries Are Runtime-Enforced, Not Policy-Checked]]
- State introspection and capability separation reinforce each other: what introspection can see is bounded by the querying principal's capability tier; the capability layer that bounds mutation also bounds observation, and the same enforcement machinery applies. Without runtime-level capability separation, an introspection endpoint would have to apply its own access control on top of the query path -- a separate enforcement layer the platform's primitive makes redundant.