Admin Observability Guide

This guide elaborates the Admin Plane and the Admin component defined in ELONN.md, in the detail needed to implement administrative observation, control, and storage consistently across Platform Components.

Normative Anchor

ELONN.md is the normative architecture of the Elonn platform. It defines the Admin Plane (Architectural Philosophy, § The Platform Has Two Planes), Admin as a Platform Component (Platform Components § Admin), and the Admin ↔ API / World / Conductor / Models / Service / Runtime boundaries (Architectural Boundaries).

This guide elaborates that architecture with implementation-guiding detail: record taxonomies, correlation patterns, storage shape, and per-component administrative capability lists. Where this guide and ELONN.md disagree, ELONN.md governs. This guide does not redefine the architecture it elaborates.

Member Plane and Admin Plane

The Member Plane is the Runtime / API / World / Conductor / Services / Providers / Models flow that performs work on behalf of Members. The Admin Plane is Admin's administrative observation of, and control over, the components of the Member Plane. See terminology/admin-plane.md and terminology/member-plane.md.

Admin-plane communication does not pass through World or Conductor merely because Member-plane communication to that component does. Normal Member-plane execution does not depend upon Admin or the successful delivery of an administrative observation. An explicit, authorized administrative operation may still intentionally change Member-plane state — it is always performed through the affected component's own administrative interface, never by Admin bypassing that component.

Administrative Interfaces

Every Platform Component — API, World, Conductor, Models, a Service, and Runtime — exposes its own administrative interface, architecturally distinct from that component's Member-plane interface. Administrative interfaces share a common capability baseline:

• component identity, version, and deployment identity
• status and health
• configuration inspection and configuration change
• maintenance state
• diagnostic capabilities
• restart or drain, where applicable

The normative shape of this shared baseline is canonical/administrative-interface.json / .md. A component may extend the baseline with component-specific administrative capabilities, but the shared fields mean the same thing everywhere they appear.

An administrative interface is not a Service Contract. Administrative operations are not Calls and do not appear in a Dataset.

Administrative Authority and Security

Member-plane authority and Admin-plane authority are distinct. Possession of member-plane authority does not grant Admin-plane authority. Administrative operations require Admin-plane authentication and authorization, and are attributable and auditable.

Administrative authority does not transfer ownership of a component's state or domain behavior to Admin. Admin directs the component that owns the affected state to perform an administrative operation through that component's own administrative interface; Admin never modifies a component's database or backing store as a substitute for that interface.

Sensitive administrative operations require stronger authorization than ordinary administrative observation. These include:

• member revocation
• password-reset assistance
• credential rotation
• key management
• security configuration
• destructive maintenance
• access-control changes

Administrative Identity and Correlation

Administrative records prefer identifiers that already exist as part of normal Member-plane execution, when those identifiers naturally identify the activity being reported. For example:

Conductor ---- Call C123 ----> Models
```

Conductor may report:

call_id = C123
operation = ...
result = ...
duration = ...

Models may independently report:

call_id = C123
model = ...
tokens = ...
cost = ...

Admin correlates the two records through C123. That identifier exists because Member-plane execution requires it — it was not introduced for administrative observation, and it is never injected into Member-plane communication solely to facilitate administration.

When no appropriate Member-plane identifier exists, a component or Admin may mint an administrative identifier: an administrative operation ID, event ID, metric record ID, incident ID, audit ID, or database identity. Administrative identifiers remain within the Admin Plane.

Observation Responsibility (Non-Duplication)

A component reports operational facts for which it is authoritative or uniquely positioned to observe. Unnecessary duplication of observations is avoided.

Conductor observes the transactions it orchestrates in both directions, and reports Calls received, planning, Service discovery and selection, Service requests and responses, Models requests and responses, retries, failures, orchestration timing, and results. Services do not duplicate those transactions solely for Admin.

Find is a worked example of ordinary Service administration: Find reports only its own internal performance — query latency, index health, backing-store behavior, and Provider failures. It does not duplicate the search Calls and results Conductor already observes when it orchestrates a Call to Find.

Models does not duplicate reasoning requests and results already observed by Conductor. Models reports model, provider, input/output/cached tokens, provider charges, calculated cost, model and provider latency, provider failures, retries and fallbacks, local-model resource utilization, and health.

World, API, and Runtimes similarly report operational facts that originate within their own architectural responsibilities.

Telemetry Record Classes

Admin accepts several classes of administrative records.

Metrics

Measurements suitable for aggregation and trend analysis: requests, errors, latency, CPU, memory, storage, queue_depth, database_latency, provider_latency, tokens, cost.

Events

Discrete operational occurrences: component_started, component_stopped, deployment_changed, health_changed, provider_failed, database_connection_lost, model_fallback, credential_rotated, member_revoked.

Execution Records

Information describing execution observed by a component: Conductor orchestration, World composition failures, API authentication failures, Runtime rendering failures, Service internal-operation failures.

Diagnostic Records

Evidence retained for investigation: request and response data, Dataset snapshots, failure details, component state snapshots, provider responses. Diagnostic records containing Member or sensitive information are subject to explicit access and retention policy.

Audit Records

Administrative operations produce audit records sufficient to establish what operation occurred, which administrative authority requested it, which component performed it, when it occurred, whether it succeeded, and the affected administrative or Member identity where applicable. Sensitive values such as credentials, passwords, tokens, and private keys are not included in audit records.

Administrative Data Streams and the Common Operational Baseline

Each component provides administrative information appropriate to its own responsibilities, in addition to the shared administrative-interface baseline (canonical/administrative-interface.json). The common operational baseline streamed over time, beyond that point-in-time status snapshot, may include: component identity, version and revision, deployment identity, lifecycle state, health, availability, request volume, error volume, latency, load, CPU use, memory use, storage use, backing-store performance, dependency health, provider health, failures, and warnings. Components additionally report operational facts specific to their own responsibilities.

The administrative-interface canonical structure captures a component's current administrative status and capability baseline. This guide's Telemetry Record Classes and operational baseline capture the richer, time-series observation stream Admin accumulates from that baseline over time. The two are related but distinct: one is a snapshot, the other is history.

Per-Component Administration

API

API owns authentication and Member access state. API's administrative operations include: inspect Member account status, disable or enable Member access, revoke Member access, invalidate sessions, facilitate password resets, revoke or rotate credentials, and perform security administration. These operations are performed by API through its own administrative interface. Admin does not directly modify API's authentication or Member databases.

World

World owns World representation and composition. World's administrative capabilities include: inspect status and configuration, change operational configuration, enter or leave maintenance state, perform diagnostics, manage operational caches, and initiate repair or maintenance operations. Administrative control of World occurs through World; Admin does not directly modify World's storage.

Conductor

Conductor owns orchestration and Service Registry. Conductor's administrative capabilities include: inspect registry state, inspect Service availability, inspect orchestration status and configuration, change operational configuration, administratively enable or disable selection of a Service or provider, enter or leave maintenance state, and perform diagnostics. Admin administers Conductor without assuming Conductor's orchestration responsibility — administratively disabling a Service or provider never grants Admin Service-selection authority, and Conductor remains the sole authority for which Service fulfills a Call.

Models

Models performs reasoning coordinated by Conductor. Models' administrative capabilities include: inspect model and provider status, enable or disable models, enable or disable providers, change model/provider configuration, manage provider credentials, inspect usage limits, enter or leave maintenance state, and perform diagnostics. Admin directs administrative policy through Models; Models remains responsible for performing reasoning and executing model/provider operations.

Mind, as a first-party Service that may expose reasoning capabilities through its own Service contract, is administered as an ordinary Service (see § Service below), not under this section. See terminology/glossary.xml's mind, models distinction.

Service

A Service owns its own domain data and behavior. A Service's administrative capabilities include: inspect status and configuration, change operational configuration, enter or leave maintenance state, enable or disable external providers, manage provider credentials, manage operational caches, initiate domain-specific maintenance, inspect dependency status, and perform diagnostics. Admin requests these operations through the Service's administrative interface; the Service performs the operation and retains authority over its own domain.

Find is a worked example: Find's administrative interface exposes its own search-index health, query latency, and Provider status, administered the same way any other Service is administered — through Find's own administrative interface, never by Admin reading Find's storage directly.

Runtime

Runtimes own presentation and operate on Member devices. Runtime administrative capabilities include: report Runtime status, version, and capabilities, report failures and performance, inspect permitted configuration, change permitted administrative configuration, request and control diagnostic capture, and perform defined maintenance or recovery operations. Administrative control of a Runtime is limited to explicitly defined capabilities; Admin authority does not imply unrestricted remote control of a Member's device.

Credential and Key Administration

The Admin Plane coordinates platform credential and key administration: credential rotation, credential revocation, provider-key replacement, certificate management, internal authentication material management, expiration monitoring, and coordinated key renewal.

The component that owns or consumes a credential remains responsible for applying and validating it. Credential and key material uses administrative transport and storage appropriate to its sensitivity. Sensitive credential material is not telemetry.

Admin Storage

Admin owns centralized administrative and operational storage:

Components
    |
    | administrative observations
    v
Admin
    |
    v
MariaDB
    |
    +---- dashboards
    +---- health
    +---- execution history
    +---- performance
    +---- cost
    +---- diagnostics
    +---- security events
    +---- audit history

Components do not depend upon Admin's storage implementation. Admin storage does not become an alternative source of component domain truth. Administrative copies of domain or Member data are evidence of observed state or execution; they are not alternative sources of domain truth.

Relationship to Service Publication, Service Contract, and Service Registry

Admin has neither a Service Publication nor a Service Contract. Admin is not indexed by Conductor's Service Registry and is never selected by Conductor to fulfill a Member Call (ELONN.md, Platform Components § Admin; Architectural Boundaries § Admin ↔ Conductor).

Administering Conductor's Service Registry — for example, inspecting registry state or administratively disabling a Service's selection — is distinct from participating in Service discovery. Admin observes and controls the Registry's administrative state; it does not search indexed Service Publications, does not retrieve Service Contracts to invoke a Service, and does not act as a candidate in Service selection.

Where Admin Is Implemented

The reference implementation of the Admin component is admin.elonn.local, named here the same way domain authority is named elsewhere in the terminology layer (for example terminology/find.md's authority: find.elonn.local) rather than in ELONN.md itself, which does not name component hosting domains.

This guide does not define admin.elonn.local's internal implementation, routes, or APIs. Those are implementation detail belonging to that repository's own documentation, out of scope for this guide.

Relationship to Other Guides

guides/platform-structure-guide.md defines where platform artifacts belong, including this guide's own place among the platform's governance documents. guides/contract-authoring-guide.md defines how Service Contracts are authored; Admin's administrative interfaces are not Service Contracts and are not governed by that guide.