Oracle Operational Ergonomics

Oracle Era 7 turns Oracle into the primary human operational interpretation layer over AncientOS. It remains read-only, advisory-only, governance-bounded, fail-closed, transport-neutral, replayable, and evidence-backed.

Oracle is not a dashboard engine, autonomy system, agent framework, hidden planner, repair loop, or mutation authority. It owns operational semantics so Discord, CLI, web, Android, or future clients can render the same reports without owning cognition.

Substrate Modules

Module	Role	Authority boundary
`app/oracle/state_model.py`	Canonical operational state snapshot for subsystems, capabilities, providers, warnings, continuity, replay, validation, inference, lanes, and transports	Builds state from bounded evidence only.
`app/oracle/readiness_graph.py`	Deterministic dependency/readiness graph	Answers readiness, degraded, blocked, dependency, downstream risk, and governance-boundary questions without execution.
`app/oracle/narration.py`	Bounded operational synthesis	Produces evidence-backed answers such as what is happening, what is degraded, why blocked, why denied, and what to inspect next.
`app/oracle/dashboard.py`	Layout-neutral report schema layer	Defines cards, panels, metrics, and visualization contracts; adapters only render.
`app/oracle/evidence_index.py`	Deterministic evidence ingestion/indexing	Indexes manifests, ontology, governance, validation, replay, and subsystem evidence with fail-closed missing-source records.
`app/oracle/situational_awareness.py`	Late-stage operational awareness substrate	Builds topology, temporal reconstruction, propagation, risk, bottleneck, drift, stable-state, and Zeus advisory surfaces without execution.
`app/oracle/operational_console.py`	Transport-neutral operational console surfaces	Renders cards, route explanations, and Oracle narration without transport-owned semantics.
`app/routing/operational_cognition_router.py`	Deterministic operator-introspection router	Separates operational awareness from execution and mutation requests.

Operational State Model

OperationalStateSnapshot contains subsystem readiness, capability readiness, provider readiness, active warnings, governance posture, replay readiness, validation health, runtime continuity health, dependency readiness, execution-lane availability, inference availability, transport health, and bounded continuity surfaces.

Provider-dependent capability readiness fails closed when explicit provider readiness evidence is absent. Oracle uses unknown rather than inventing healthy provider state.

Readiness Graph

Oracle readiness graph nodes represent subsystems, providers, and governed capabilities. Edges represent depends_on relationships from capability contracts and provider bindings.

flowchart LR Observe["capability.observe.runtime_state"] Plan["capability.plan.preview"] Execute["capability.execute.confirmed_lane"] Executor["provider.executor.confirmation_runner"] Inference["capability.infer.provider_role"] RoleAdapter["provider.inference.role_adapter"] Plan --> Observe Execute --> Plan Execute --> Executor Inference --> RoleAdapter

Example interpretations:

provider.inference.role_adapter=unknown blocks capability.infer.provider_role.
capability.publish.transport_message is degraded because it is transport-specific and must stay behind an adapter boundary.
capability.autonomy.recursive_execution is forbidden and emits advisory autonomy-drift/forbidden-capability visibility.

Report Surfaces

Oracle structured surfaces include operator, subsystem, capability, governance, degradation, readiness, execution-boundary, architecture, constitutional warning, dashboard, topology health, dependency propagation, operational narrative continuity, governance risk, readiness drift, stable-state comparison, bottleneck analysis, and operational situation summaries.

Adapters may render these into Discord messages, CLI output, web components, or Android views. They must not reinterpret readiness, unblock capabilities, execute recommendations, or own operational cognition.

Conversational Routing Ergonomics

Luna routes operator-introspection requests through the operational console before generic execution/governance staging. Examples:

What is the current operational posture? -> operational awareness.
What workflows are blocked? -> workflow-state analysis.
Show replay continuity -> replay inspection.
What capabilities are available? -> capability inspection.
What governance boundaries exist? -> governance inspection.
What constitutional risks exist? -> constitutional inspection.

Execution-looking requests such as execute the coordination proposal, delete the workflow state file, or dangerous shell-like mutations are not handled as operational cognition. They remain subject to governed execution and approval paths.

Narration Examples

What is happening? reports ready node count, degraded/blocked node count, replay readiness, and authority boundary from indexed evidence.

What is degraded? lists graph nodes whose status is not ready, including blockers and evidence paths.

Why is this blocked? combines direct blockers with upstream dependency status. Unknown nodes fail closed as unknown_node_fails_closed.

Why was this capability denied? uses a supplied capability arbitration report to explain deterministic denial reasons, required evidence artifacts, and governance boundaries.

Operational Topology Examples

Canonical topology nodes include:

capability.infer.provider_role
provider.inference.role_adapter
governance:approval_gated
execution_lane:approval_bound_executor
evidence_domain:replay

Canonical topology edges include:

capability.execute.confirmed_lane -> capability.plan.preview as readiness_dependency
capability.infer.provider_role -> provider.inference.role_adapter as provider_dependency
capability.publish.transport_message -> governance:approval_gated as governance_boundary
capability.execute.confirmed_lane -> execution_lane:approval_bound_executor as execution_lane_boundary

Topology integrity validation reports missing edge endpoints, self-dependencies, and validated topology state as replayable findings.

Propagation And Lineage Examples

Readiness propagation remains advisory-only:

If provider.inference.role_adapter=unknown, capability.infer.provider_role is blocked through a provider dependency.
If execution_lane:approval_bound_executor=unknown, mutation-capability readiness can propagate lane degradation without granting repair authority.
If a replay evidence node is blocked, replay invalidation propagates only as report evidence.
If a forbidden capability is degraded by governance:forbidden, the dependency propagation report records a governance-boundary blockage.

Temporal reconstruction compares supplied OperationalStateSnapshot artifacts. For example, a previous snapshot with provider.inference.role_adapter=ready and a current snapshot with provider.inference.role_adapter=unknown produces a deterministic transition event from ready to unknown. Oracle does not use conversation transcripts to infer that transition.

Stable-State And Drift Examples

ReadinessDriftReport compares a replay-safe baseline to current state. Common deltas include provider readiness moving from ready to unknown, capability readiness moving from ready to blocked, replay readiness changing from ready to blocked, and validation health remaining unknown_without_validation_artifact.

StableStateComparisonReport selects the last supplied snapshot where replay readiness is ready and all providers are ready. If no such snapshot is supplied, the report says stable state is unavailable rather than inventing a healthy baseline.

Constitutional Visibility

Oracle surfaces warnings only. It does not remediate them.

Warning categories include doctrine drift, transport coupling, provider overreach, authority expansion, autonomy drift, governance bypass, replayability violations, capability contract violations, provider health, and execution-boundary visibility.

GovernanceRiskReport normalizes these into constitutional risk categories: transport-cognition leakage, provider-authority drift, autonomy creep, governance bypass risk, replayability violation, capability-contract violation, hidden-state accumulation, unsafe dependency coupling, authority-boundary erosion, and deterministic-boundary visibility.

Example warnings:

capability.autonomy.recursive_execution is forbidden and non-replayable.
Provider-backed inference may drift into provider-owned authority if used for routing or execution decisions.
Transport publication must stay behind adapter boundaries and explicit approval requirements.

Continuity Ergonomics

Oracle continuity surfaces expose active objective visibility, unresolved clarification visibility, pending approval visibility, blocked workflow visibility, next safe action visibility, and replay continuity visibility.

Runtime operational-console continuity stores bounded focus only: active operational focus, route class, last route decision, workflow summary, and next safe inspection suggestion. It does not retain transcripts or create authority.

Oracle does not retain transcript memory, create hidden long-term memory, or expand authority from continuity state.

Future Zeus Integration

Zeus can consume Oracle constitutional warnings, readiness graphs, degradation summaries, and evidence indexes as advisory supervision inputs. Zeus must continue to propose or evaluate through governed paths; Oracle warnings do not grant repair or execution authority.

Late-stage hooks add constitutional risk surfaces, topology drift warnings, readiness degradation chains, operational bottleneck analysis, governance-boundary erosion warnings, provider-overreach analysis, and replayability integrity warnings. Each hook is metadata-only with authority_transfer=false and execution_coupling=false.

Future Underlord Integration

Underlord can consume Oracle report surfaces as investment-aware escalation evidence. Oracle can show provider overreach, paid-provider readiness, and approval boundaries, but Underlord remains the explicit paid-escalation gate. Underlord should use these reports as evidence for human review, not as direct approval, budget-spend, provider-call, or remediation authority.

Future UI Adapter Notes

Future UI adapters should render OracleDashboardSurface panels and VisualizationContract entries. They should treat card_id, status, metrics, evidence, dependencies, blockers, and governance_boundaries as semantic fields from the substrate, not UI-local logic.

Human Review Questions

Which runtime provider-health artifact should become canonical for marking providers ready instead of unknown?
Which validation artifact path should Oracle promote as the canonical latest validation-health input?
Should execution-lane availability remain summary-only, or should each lane receive a file-backed readiness artifact?
Which Zeus warnings should remain Oracle-only visibility versus future Zeus supervision inputs?
What continuity artifact should represent unresolved clarification and pending approval state across transports?
Which replay artifact should become canonical for long-horizon operational timelines across restarts?
Should topology baselines be stored as versioned machine manifests or derived solely from current ontology and architecture evidence?