Oracle Operational Ergonomics

Status: completed Era 7 capability surface.

Oracle Era 7 established Oracle as 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 can inspect governed actions, render the scoped action queue, validate preflight state, accept bounded proposal vocabulary, delegate explicit apply requests to the existing governed executor, and audit durable lifecycle records. These operator ergonomics do not give Oracle approval, execution, evidence, receipt, or memory authority and do not create a second proposal lifecycle.

Portfolio reporting boundary

Oracle may render completed, adopted, blocked, candidate, and deferred portfolio records from canonical evidence. It may recommend that the operator review a candidate or blocker. It cannot change portfolio lifecycle state, select an implementation program, or treat a recommendation as adoption. When no work is adopted, Oracle reports that fact and asks for an explicit operator adoption decision.

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.

Governed Action Queue

Oracle, show my action queue. renders a bounded, deterministic, read-only view of actionable governed-action proposals in the current conversation and actor scope. It correlates lifecycle, Lich approval, and canonical preflight state without copying records or creating a queue store. Targets are fingerprinted; proposal payloads and file content are never shown. blocked means canonical preflight found blockers, while unknown means preflight was unavailable.

Governed Proposal Audit

Oracle, audit proposal <proposal-id>. requires exactly one explicit scoped ID and renders a bounded chronological correlation of the existing proposal, Lich approval and binding, Zeus evidence, execution or rollback receipts, and Kernel Record reference. Missing links are explicit gaps. Target identifiers are fingerprinted and file content, command payloads, and environment data are not rendered. Ordering uses timestamp, lifecycle phase rank, record type, and ID; the audit creates no records and changes no lifecycle state.

Simplified Proposal Intake

Oracle, propose changing file <relative-target> from "<exact-old>" to "<exact-new>". is a deterministic grammar over the existing bounded governed-action builder. All three parameters are mandatory and conversation history supplies none of them. Path, symlink, file-size, UTF-8, exact-match, evidence, hash, expiry, scope, persistence, and Lich requirements are unchanged. The response returns the existing proposal ID, states that no mutation occurred, and offers explicit validate, inspect, and governed approval next steps.

Explicit Governed Apply

Oracle, apply approved proposal <proposal-id>. requires exactly one explicit ID and is vocabulary over the existing governed executor. It neither approves nor combines approval with execution. The canonical preflight, exact Lich binding, lifecycle lock, atomic target precondition, Zeus before/after evidence, durable receipt, and separately approved rollback semantics remain unchanged. Ambiguous, missing, unknown, out-of-scope, unapproved, expired, stale, disabled, already-executed, and rollback-only requests fail closed. Successful rendering names the receipt and lifecycle and explicitly disclaims Oracle authority.

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?