GovEngine

GovEngine is a carrier-agnostic deterministic governed-runtime kernel for portable artifact governance and policy-gated controlled execution.

It consumes SCLite as its contract lifecycle layer and provides reusable services around artifact state/transition boundaries, policy decisions, execution-contract shaping, execution-ticket checks, command-shape normalization, dry-run result assembly, and neutral runtime/control projections. Security-domain action, tool, scope, and signal behavior is host-owned; the published 0.12 alpha line removes the former Ravenclaw-derived compatibility helpers.

Why it exists

AI-assisted security workflows need a hard boundary between:

1. what an agent or caller wants;
2. what policy allows;
3. what execution shape was prepared;
4. what was approved;
5. what was dry-run or executed;
6. what evidence can be reviewed.

SCLite defines the auditable contract artifacts for that lifecycle. GovEngine is the reusable Python service layer that consumes those contracts and helps a host runtime enforce them without relying on prompt text alone.

Dependency direction

Ravenclaw -> GovEngine -> SCLite

• SCLite owns schema-backed lifecycle artifacts and validation.
• GovEngine owns reusable governed-execution helpers that consume SCLite artifacts.
• Ravenclaw remains the reference security runtime/control plane and concrete integration host.
• Tecrax is reserved as a future infrastructure-operations runtime/profile on the same foundation.

GovEngine is not Ravenclaw, Tecrax, Logdash, an LLM agent loop, a scanner, or a protocol adapter.

What GovEngine includes now

• a public surface registry covering neutral artifact-governance, planning, admission/policy, evidence-review, domain-profile, runtime-proof, and controlled-execution surfaces;
• serializable kernel/profile/runtime/SCLite boundary contracts and a machine-readable boundary report;
• execution-contract shaping/redaction helpers;
• artifact descriptor/state/transition boundary helpers;
• SCLite lifecycle status bridge and lightweight lifecycle transition gate/controller;
• guarded-root replay checks for already-verified SCLite Kernel Guard sidecars;
• high-level guarded-strict verification plus replay-fresh runtime decisions;
• artifact deconfliction/change-order helpers and lightweight state-index summaries;
• signature/trust policy bridge helpers with host-provided signer/verifier ports and deterministic demo ports for fixtures;
• approved-spec and execution-ticket validation helpers;
• controlled execution gate helpers with dry-run as the default runner path;
• command-shape helpers;
• dry-run result assembly helpers;
• deterministic orchestration handoff, governance event envelope, run-state, and between-step control-decision contracts;
• neutral runtime-shell contracts for host control actions, queue snapshots, runtime snapshots, and scheduler-tick metadata;
• neutral planning contracts for task, plan-intent, and planner-port handoffs;
• neutral admission, policy, approval, and audit contracts for host runtime gates;
• explicit SCLite integration seams;
• focused standalone pytest coverage and GitHub Actions CI.

What it intentionally does not include yet

• live subprocess execution backend;
• raw artifact storage/writes;
• Logdash UI/API routes;
• OpenClaw, MCP, A2A, or other protocol adapters;
• LLM provider integrations;
• Ravenclaw-specific personas, workspace state, or campaign UX;
• production-readiness claims;
• PKI, CA, KMS, key storage, or production identity proof.

Current status

GovEngine is an alpha package 0.12.1a1 (0.12.1-alpha.1). It keeps the neutral artifact-governance, planning, admission/policy, controlled-execution, runner-supervision, runtime-shell, evidence-review, profile, and proof surfaces while removing the former optional security-profile facade and Ravenclaw-derived helper modules. The active dependency line is sclite-core>=0.8.0b2,<0.9. The current published PyPI package is govengine==0.12.1a1.

Installation

Install the currently published public alpha package from PyPI with an exact version pin:

python -m pip install govengine==0.12.1a1

GovEngine depends on the PyPI distribution sclite-core while preserving the Python import package sclite.

For local development:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest -q

Minimal smoke example

from govengine import public_surface_index
from govengine.execution.runner import approved_spec_dry_run_result

assert [surface.name for surface in public_surface_index()] == [
    "artifact_governance_core",
    "planning_contracts_core",
    "admission_policy_core",
    "evidence_review_core",
    "domain_profile_sdk",
    "runtime_contract_proofs",
    "controlled_execution_core",
]

receipt = approved_spec_dry_run_result(
    approved_execution_spec={
        "action_type": "bounded_request",
        "capability": "fixture_review",
        "resolved_tool": "fixture",
        "execution_mode": "dry_run",
    },
    planned_commands=[["fixture", "review"]],
)
assert receipt["status"] == "dry-run"

Documentation

• PUBLIC_STATUS.md — current maturity and non-claims.
• CHANGELOG.md — notable public changes.
• CONTRIBUTING.md — contribution and boundary rules.
• SECURITY.md — security reporting and package safety boundaries.
• PUBLISHING.md — publishing/PyPI readiness checklist.
• docs/ARCHITECTURE.md — package shape and dependency boundaries.
• docs/SCLITE_INTEGRATION.md — how GovEngine consumes SCLite.
• docs/API_BOUNDARY.md — owned vs excluded surfaces.
• docs/GOVENGINE_KERNEL_BOUNDARY.md — kernel/profile/runtime/SCLite ownership split.
• docs/DOMAIN_PROFILE_CONTRACT.md — domain profile contract and conformance rules.
• docs/ORCHESTRATOR_MODEL.md — deterministic orchestration boundary and runtime non-claims.
• docs/EVENT_MODEL.md — neutral governance event metadata and payload boundaries.
• docs/STATE_MACHINE.md — neutral run-state and transition contract.
• docs/CONTROL_MODEL.md — between-step control decisions and state-machine delegation.
• docs/RUNTIME_SHELL.md — neutral host runtime/control projection contracts.
• docs/VALIDATION.md — local checks and non-claims.
• docs/ROADMAP.md — staged extraction roadmap.

License and provenance

GovEngine is MIT-licensed. It was extracted from Ravenclaw in contract-first stages, so LICENSE preserves the copyright notice for the originating Ravenclaw contribution lineage. The author metadata in pyproject.toml identifies the GovEngine package maintainer; it does not replace or reassign the originating copyright notice.

Safety boundary

GovEngine should preserve deterministic governance over prompt-only behavior. GovEngine must never execute directly from raw intent: execution requires a prepared execution contract, valid policy decision, approved execution ticket, valid signature/trust decision, and allowed runner profile. When a SCLite bundle is runtime-consumable, the execution gate also requires a guarded-strict SCLite verification result and replay-fresh GovEngine decision; review-only bundles can remain on weaker review/integrity postures without becoming execution authority.

DryRunRunner/dry-run behavior remains the default. Live execution backends are disabled by default; any future LocalSubprocessRunner must be optional, policy-enabled, negative-tested, and never the default. Controlled execution depends on lifecycle gates and signing/trust gates, with Ravenclaw retaining the concrete runtime adapter until reviewed. Demo signing helpers are fixture ports only: they bind a deterministic signature to an artifact digest for tests/reviewer demos and must not be presented as cryptographic identity, PKI, CA, KMS, or trust-store support.