governance package

Reviewed against commit 8a2cb42ad on 2026-10-23.

Reference: package page (28 modules, 6,865 lines; six of them in escalation_handler) · key modules: policy_engine, prolog_gate, prolog_client, constitutional, policy_layers, verdict. Governance as one of orchestrata's defining choices is explained in the overview.

The story

Orchestrata is a multi-agent system in which autonomous "volk" agents plan, write, and review code — and an autonomous agent that can execute arbitrary work needs a referee. That is what orchestrata_ultimate.governance is: the policy engine, escalation, audit, and constitutional-enforcement layer that decides whether an agent may do what it is about to do, records what was decided, and escalates when the answer is contested. The package is a merge of two source trees from the original monorepo — src/governance/ (policy engine, ethical, constitutional, monitoring) and src/core/governance/ (escalation handler, conflict resolver, SLA tracker) — which is why it contains both a decision-making core and a full multi-hop escalation subsystem (US-005).

The heart of the package is Prolog-backed decision making. Rules live in .pl files (constitutional articles, ethics, resource-access policy) and are consulted through GovernancePrologClient (prolog_client.py), a governance-flavoured wrapper over the shared PrologBridge/janus engine. When a request arrives — "may agent X perform action Y in context Z?" — it flows into PolicyEngine (policy_engine.py), the central decision point implementing the IPolicyEngine protocol. The engine first checks GovernanceCache for a previously computed decision, then fans out to its collaborators: ConstitutionalEnforcer (all 11 constitutional articles, evaluated as Prolog queries), EthicalBoundary (harm/deception/privacy/bias checks against ethics.pl), and its own policy rules. The outcome is a typed PolicyDecision (types.py), which is written to the GovernanceAudit trail, counted by GovernanceMonitoring, and — if the action was denied — recorded by ViolationTracker. Repeated or severe violations can push the system into a degraded state via SafeModeManager. A separate, lower-level runtime hook exists in prolog_gate.py: PrologGate exposes the raw may_execute / may_complete predicates that the kernel dispatcher calls before letting a pipeline stage run or complete, with _strict.py supplying the call-time ORCHESTRATA_GOVERNANCE_STRICT flag that makes governance fail closed by default (ADR-009).

Not every disagreement can be settled by a rule lookup. When agents conflict — over resources, priorities, or contradictory decisions — the escalation_handler/ subpackage takes over. ConflictResolver detects and classifies Conflicts and attempts resolution strategies; unresolved conflicts are driven by AdvancedEscalationHandler through successive EscalationHops up the agent hierarchy, while EscalationSLATracker watches the clock and fires NotificationChannel alerts when an escalation breaches its SLA. Every hop and resolution is persisted to the graph audit trail (the operational graph orchkg; Neo4j until its retirement on 2026-07-27), so escalations are replayable and inspectable after the fact.

Around it, governance collaborates with its neighbours rather than acting alone: it leans on core for the Prolog adapter/bridge, infra config, Redis state, graph audit writers, and the @traces requirement decorators that stitch code back to specs; the kernel dispatcher and postman router call into the gate and policy engine before moving work; and EventEmittingPolicyEngine wraps the engine so every decision is broadcast as an event that the gateway and observability layers can surface in real time. For a new engineer, the mental model is simple: rules in Prolog, decisions through PolicyEngine or PrologGate, evidence in Redis and the graph, and disagreements up the escalation ladder.

Key responsibilities

• Decide whether an actor may perform an action in a given context — synchronously via PrologGate.may_execute / may_complete at the kernel dispatcher, or richly via PolicyEngine.evaluate returning a typed PolicyDecision.
• Enforce the constitution — evaluate all 12 constitutional articles (ARTICLE_COUNT = 12 in constants.py) as Prolog queries, flag actions that need human consent, and record human overrides (ConstitutionalEnforcer).
• Enforce ethical boundaries — detect harm, deception, privacy violations, and bias before an action runs (EthicalBoundary).
• Gate resource access — file, network, API, and database access decisions against policy (ResourceAccessController).
• Remember and observe — cache decisions across a local + Redis tier (GovernanceCache), write an audit trail (GovernanceAudit), and track latency/throughput/violation metrics (GovernanceMonitoring).
• Degrade safely — count violations (ViolationTracker) and trip a system-wide SafeModeManager when the violation rate crosses threshold.
• Escalate contested decisions — detect and resolve conflicts (ConflictResolver), drive multi-hop escalation up the hierarchy (AdvancedEscalationHandler), and enforce SLAs with breach notifications (EscalationSLATracker).
• Fail closed by default — _strict.py reads ORCHESTRATA_GOVERNANCE_STRICT at call time so an unavailable rule base denies rather than allows (ADR-009). PrologGate.may_execute is an exception at commit 8a2cb42ad: with no rules loaded it returns allow ("Prolog not loaded — permissive mode") whatever the strict flag says, and records the allow as an error verdict.

Class diagram

Decision core

PolicyEngine is where a governance question becomes an answer. It composes the constitutional and ethical enforcers, and all of them query Prolog through the shared GovernancePrologClient. PrologGate is the separate low-level runtime hook the kernel calls to admit or complete pipeline stages. Generated from the AST and render-verified:

Evidence & safeguards

Every decision leaves a trail and feeds the safety machinery. The cache short-circuits repeat queries, the audit trail and monitoring record what happened, violations accumulate, and a rising violation rate trips safe mode. ResourceAccessController is the specialised gate for file/network/API/database access.

Escalation subsystem (escalation_handler/)

When a rule lookup cannot settle a disagreement, the escalation subsystem takes over: conflicts are detected and (where possible) resolved, otherwise handed up the hierarchy hop by hop, with an SLA tracker firing notifications on breach.

Inheritance & protocol overview

The protocol contracts (interfaces.py) and their concrete implementations, plus the enum and exception hierarchies. Generated from the AST, render-verified:

Module dependency diagram

Internal module imports within orchestrata_ultimate.governance (generated from the AST, render-verified):

Module inventory

policy_engine.py

PolicyEngine is where a governance question becomes an answer. It implements the IPolicyEngine protocol and composes nearly everything else in the package: as the module dependency diagram shows, it imports the cache, the constitutional and ethical enforcers, audit, monitoring, safe mode, violations, and the Prolog client. An incoming action is checked against the cache first, evaluated against the Prolog rule base and its collaborators, and the resulting PolicyDecision is simultaneously audited, counted, and — on denial — turned into a tracked Violation. event_emitting_policy_engine.py wraps this engine in EventEmittingPolicyEngine, which emits an event for every decision so the gateway and monitoring surfaces can observe governance outcomes as they happen, without the engine itself knowing about any event bus.

Class map (generated)

Generated from the live source AST by scripts/gen-module-class-diagrams.py — do not hand-edit. Abstract classes have a green border; members listed are those defined on the class itself (inherited members excluded). Solid empty-triangle arrows = in-package inheritance; dashed arrows into dashed boxes = external/stdlib/cross-package bases; filled diamond = composition (constructed in __init__); open diamond = aggregation (annotated/injected reference); diamond edge labels name the owning attribute.