govengine 0.7.0

Carrier-agnostic artifact governance and controlled-execution services that consume SCLite contract lifecycle artifacts.

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-oriented action/tool/scope/signal helpers remain available as an optional profile for hosts such as Ravenclaw, not as the neutral core itself.

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 that separates neutral artifact-governance core, controlled-execution core, and optional security-profile helpers;
• an explicit govengine.security_profile facade for optional security-profile helper discovery;
• 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;
• 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;
• optional security-profile helpers for action schema/validation/compilation, capability recipes, tool registry, semantic-loss policy, scope checks, policy gateway, and signal/analysis/evidence-confirmation contracts;
• 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 a pre-alpha 0.7.x helper package. The package is importable and tested. The 0.1.3 line added artifact-governance control gates while keeping live execution disabled by default. The 0.1.4 line added a surface registry that separates the neutral core from optional security-profile helpers. The 0.1.5 line adds a security-profile facade for one-entrypoint helper discovery. The 0.1.6 line consumes sclite-core>=0.3.5,<0.4, includes thin scoped-ticket / receipt-bounded-evidence gates, and contains deterministic demo signer/verifier ports for host proof fixtures; those ports exercise signing/trust seams without claiming PKI/key ownership. The 0.1.7 line consumes sclite-core>=0.5.1,<0.6 and adds a thin SCLite review-bundle bridge for the packaged GovEngine integration fixtures. The 0.2.0 line freezes the initial kernel/profile boundary with govengine.boundary, govengine.orchestration, govengine.events, govengine.state_machine, and govengine.control while keeping live execution, queue/scheduler ownership, carrier adapters, credential handling, and runtime persistence outside GovEngine. The 0.3.0 line adds govengine.runtime_shell for neutral host control actions, queue snapshots, runtime snapshots, and scheduler-tick metadata without making GovEngine own host storage, scheduling, UI, adapters, credentials, or concrete execution. The 0.4.0 line adds govengine.planning for neutral task-contract, plan-intent, and planner-port validation without making GovEngine own planner implementations, raw targets/prompts, Ravenclaw security semantics, queues, schedulers, adapters, commands, or live execution. The 0.5.0 line adds govengine.admission for neutral admission, policy-decision, approval-request, and audit-record validation without making GovEngine own profile policy meaning, approval workflows, audit storage, adapters, commands, or live execution. The 0.6.0 line adds govengine.execution.supervision for neutral runner leases, supervision plans, supervision decisions, and request/receipt validation while keeping live backends disabled by default and host-owned. The 0.7.0 line adds govengine.review for neutral evidence requirements, claims, qualifications, and review results without making GovEngine own SCLite review verdicts, Ravenclaw finding taxonomy, raw evidence storage, or live execution. Ravenclaw has host adapters for these gates/projections and still owns concrete runtime execution.

Installation

Install the current public package from PyPI:

python -m pip install govengine

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, security_profile_index
from govengine.action_compiler import compile_action_spec
from govengine.execution.runner import legacy_action_spec_dry_run_result

assert [surface.name for surface in public_surface_index()] == [
    "artifact_governance_core",
    "controlled_execution_core",
    "security_profile_helpers",
]
assert security_profile_index()["entrypoint"] == "govengine.security_profile"

compiled = compile_action_spec({
    "action_type": "single_probe",
    "capability": "http_probe",
    "tool": "curl",
    "args": ["https://example.com"],
})

receipt = legacy_action_spec_dry_run_result(
    compiled_action=compiled,
    planned_commands=[["curl", "https://example.com"]],
)
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.

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.

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.