Administrative Interface

Purpose

Describes the current administrative state and capability baseline a Platform Component's administrative interface reports to Admin.

An Administrative Interface document is not a Dataset. It is not returned in response to a Member-plane Call, and it does not participate in World composition.

Responsibilities

• Identify the reporting component and its deployed version.
• Report the component's current operational status and health.
• Report which configuration keys are administratively inspectable and which are mutable.
• Report the component's current maintenance state.
• Report which diagnostic capabilities the component makes available.
• Report whether the component supports administrative restart or drain, and the component's current state for each.

Used By

• Admin
• API
• World
• Conductor
• Models
• Service
• Runtime

Structure

An Administrative Interface document contains:

• component
• component_version
• deployment_id
• status
• health
• configuration
• maintenance
• diagnostics
• control
• observed_at
• metadata

The canonical structure is defined in administrative-interface.json.

Semantics

component identifies the reporting Platform Component by its canonical name (for example API, World, Conductor, Models, the name of a Service, or Admin itself).

component_version is the reporting component's own version or revision identifier.

deployment_id identifies the specific deployed instance reporting, when the component's deployment topology makes instance-level identity meaningful. Empty when the component does not distinguish instances.

status is the component's current lifecycle state (for example starting, running, degraded, stopped). Values are component-defined and extensible, the same way availability.state is extensible on an Action.

health describes the component's aggregate health:

• state — an aggregate health signal (for example healthy, degraded, unhealthy).
• checks — zero or more component-defined individual check results. Empty when the component does not decompose health into sub-checks.

configuration describes administrative configuration access:

• inspectable — a map of configuration keys the component exposes for administrative inspection, and their current values.
• mutable — the subset of those keys that may be administratively changed through the component's administrative interface. This document reports which keys are mutable; it does not itself carry a configuration change.

maintenance carries state and reason, the same shape as Action's availability. state is for example normal, entering, maintenance, or leaving. reason is administrator-facing copy explaining a non-normal state, empty otherwise.

diagnostics.available lists the diagnostic capabilities the component currently exposes (for example request_trace, state_snapshot). It does not carry diagnostic evidence itself.

control.restart and control.drain each carry state and reason, the same shape as Action's availability. state communicates whether the operation is currently offered (for example available or unavailable for restart; available, draining, drained, or unavailable for drain). reason is administrator-facing copy explaining an unavailable state, empty otherwise.

observed_at is the timestamp at which the reporting component produced this snapshot.

metadata carries component-specific administrative extensions beyond the shared baseline, the same role metadata plays on Action and Object.

Scope

An Administrative Interface document describes administrative status and capability only.

It does not define:

• the administrative operations used to request a configuration change, restart, or drain (component-specific; defined by each component's own administrative interface, outside the Canonical Data Model)
• Member-plane business logic or domain data
• audit, metric, or event record formats (administrative observation detail; see the Admin Observability Guide)
• credential or key material

Invariants

• An Administrative Interface document is reported by exactly one Platform Component about itself.
• An Administrative Interface document is not a Dataset and is never returned in response to a Member-plane Call.
• configuration.inspectable never includes credential or key material.
• A component's administrative interface, not Admin, remains authoritative for whether a reported status, health, maintenance, or control value is accurate.

Related Models

• Object
• Action
• Error