GovEngine

GovEngine is an alpha package 0.14.0 (0.14.0) for deterministic governance-kernel contracts.

It consumes SCLite as the lower truth layer and exposes reusable Python records, validators, and composition helpers for admission decisions, lifecycle gates, policy/trust summaries, receipt binding, evidence review, replay freshness, and profile conformance. It does not run jobs. It does not own host runtime behavior. The published 0.14.0 alpha line keeps Ravenclaw, Tecrax, carrier adapters, concrete schedulers, credential handling, and live execution outside the kernel.

Dependency Direction

Ravenclaw -> GovEngine -> SCLite

• SCLite owns artifact lifecycle schemas, canonical descriptors, ordered hash-chain verification, guarded verification, tickets, receipts, and evidence truth records.
• GovEngine owns deterministic governance contracts over those truth records: admission envelopes, policy/trust/replay decisions, lifecycle state mapping, receipt/evidence binding, review qualification, profile conformance, and public-safe contract fixtures.
• Ravenclaw owns the concrete security runtime, operator workflow, storage, adapters, target semantics, and live tool behavior.
• Tecrax is a future governed-autoadmin/domain runtime consumer; its current GovEngine presence is a conformance fixture, not a runtime implementation.

GovEngine is not SCLite, Ravenclaw, Tecrax, Logdash, an LLM loop, a scanner, a scheduler, a credential manager, a replay database, a PKI/KMS layer, or a subprocess runner.

What GovEngine Includes Now

The public surface registry is govengine.surfaces.public_surface_index(). It currently reports seven alpha surfaces:

• artifact_governance_core for artifact descriptors, lifecycle state mapping, transition decisions, signing/trust records, guarded-root replay decisions, state-index helpers, deconfliction, and the SCLite bridge.
• planning_contracts_core for neutral task, plan-intent, and planner-port handoff records. These are handoff contracts, not a planner.
• admission_policy_core for RuntimeAdmissionResult, policy/admission/approval/audit records, proof-input validation, public summaries, bounded artifact references, and the development-only JSONL audit-ledger adapter.
• evidence_review_core for receipt-bounded evidence requirements, claims, qualifications, review results, and evidence-review-chain validation.
• domain_profile_sdk for contract-only domain profile declarations and conformance reports, including Ravenclaw and Tecrax fixture profiles.
• runtime_contract_proofs for public-safe conformance artifacts over Ravenclaw and Tecrax contract shapes. They are fixtures, not runtime authorization.
• controlled_execution_core for approved-spec checks, execution-ticket gates, command-shape normalization, runner request/receipt boundaries, supervision records, dry-run helpers, runtime-shell projections, event/control records, OODA records, and orchestration handoff records.

The 0.14.0 line also adds:

• canonical lifecycle vocabulary: verified_chain and verified_lifecycle are the current names, while chain_verified and lifecycle_verified remain migration aliases only;
• stricter signature transition behavior: failed verification can no longer pass solely because a separate trust status says trusted;
• bounded evidence-kind enforcement through GovEvidenceRequirement.evidence_kind, without adding a raw evidence store or domain evidence taxonomy;
• clearer runtime guard failure reporting through the kernel_guard_required reason code instead of overloading signature failures;
• stricter runtime-admission proof inputs for execution-ticket id, ticket digest/reference, guarded root digest, and admission/ticket receipt binding;
• mypy, ruff, public-truth, alpha-readiness, and documentation anti-drift gates that protect version truth, lifecycle vocabulary, runtime-shell/state-machine separation, and contract-proof classification.

Current Status

GovEngine is the published 0.14.0 alpha line. The package dependency is sclite-core>=1.0.3,<1.1, and the Python import package remains sclite.

The current kernel is useful for deterministic review of prepared governance records. It is not production runtime readiness and it is not an execution authority. RuntimeAdmissionResult is the single canonical admission envelope; compose_runtime_admission_result() composes host-supplied gate summaries into that envelope, and validate_runtime_admission_result() checks the envelope shape. These helpers do not verify SCLite artifacts, persist replay claims, approve operators, or execute commands by themselves.

When hosts need a runtime-consumable path, the intended chain is:

1. SCLite verifies the artifact lifecycle and guarded truth records.
2. GovEngine maps the lifecycle status and validates proof-input summaries.
3. GovEngine composes policy, ticket, trust, replay freshness, runner profile, receipt obligation, blockers, and next actions into RuntimeAdmissionResult.
4. Host runtime code decides what to do with that result under its own operator, credential, storage, scheduler, and execution controls.

Dry-run remains the default local execution posture. Any live backend belongs outside this package until a separate host/runtime boundary explicitly owns and tests it.

Explicit Non-Claims

GovEngine does not provide:

• live subprocess execution;
• raw-intent execution;
• scanner, exploit, campaign, or target authorization;
• scheduler, queue persistence, long-running worker, or LLM agent loop;
• credential handling, private key storage, CA, PKI, KMS, HSM, trust-anchor management, rotation, or revocation;
• production replay database or production audit database;
• raw artifact store or raw evidence store;
• SCLite schema authority, SCLite canonicalization, SCLite hash-chain verification, or SCLite Kernel Guard HMAC verification;
• Ravenclaw security taxonomy, target semantics, campaign UX, public proof projection, or runtime adapters;
• Tecrax infrastructure semantics, infrastructure credentials, or runtime adapters;
• carrier adapters such as OpenClaw, MCP, A2A, HTTP APIs, or UI routes;
• stable 1.0 API guarantees.

Installation

Install the latest published package from PyPI:

python -m pip install govengine

For local development:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest -q
python -m mypy govengine
python -m ruff check .
python scripts/validate_public_truth.py
python scripts/validate_alpha_readiness.py

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"

Validation

The current package-line gate is intentionally local and deterministic:

python -m pytest -q
python -m mypy govengine
python -m ruff check .
python scripts/validate_public_truth.py
python scripts/validate_alpha_readiness.py
python scripts/validate_clean_package_install.py --no-editable

scripts/validate_public_truth.py keeps package metadata, public docs, dependency truth, public surface names, and release labels aligned. scripts/validate_alpha_readiness.py checks the alpha package posture before publication. scripts/validate_clean_package_install.py --no-editable validates an installed wheel in isolation and uses scoped pip check instead of a broad system interpreter.

Documentation

• PUBLIC_STATUS.md records the active package status and non-claims.
• CHANGELOG.md records release changes.
• CONTRIBUTING.md records contribution and boundary rules.
• SECURITY.md records security reporting and package safety boundaries.
• PUBLISHING.md records PyPI release checks.
• docs/ARCHITECTURE.md explains package shape and dependency boundaries.
• docs/API_BOUNDARY.md maps owned and excluded surfaces.
• docs/API_STABILITY_MATRIX.md classifies public exports.
• docs/GOVENGINE_KERNEL_BOUNDARY.md defines kernel/profile/runtime/SCLite ownership.
• docs/SCLITE_INTEGRATION.md explains how GovEngine consumes SCLite.
• docs/RUNTIME_ADMISSION.md describes the canonical runtime admission envelope.
• docs/INSPECT_ONLY_ADMISSION_WORKFLOW.md documents read-only admission inspection.
• docs/GUARDED_FRESH_RUNTIME_ADMISSION_EXAMPLE.md shows guarded-strict plus replay-fresh admission input.
• docs/RECEIPT_BINDING.md documents admission/ticket/request/receipt binding.
• docs/EVIDENCE_REVIEW.md documents receipt-bounded evidence review.
• docs/ADMISSION_POLICY.md documents admission, policy, approval, audit, and audit-ledger contracts.
• docs/RUNNER_SUPERVISION.md documents runner request, receipt, supervision, and live-runner safety boundaries.
• docs/LOCAL_SUBPROCESS_RUNNER_DECISION.md records why no live subprocess runner ships now.
• docs/DOMAIN_PROFILE_CONTRACT.md documents profile contracts and conformance.
• docs/ORCHESTRATOR_MODEL.md, docs/EVENT_MODEL.md, docs/STATE_MACHINE.md, docs/CONTROL_MODEL.md, and docs/RUNTIME_SHELL.md separate deterministic handoff/projection records from host runtime execution.
• docs/VALIDATION.md records current and historical validation evidence.
• docs/ROADMAP.md records the 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. It must not execute directly from raw intent. Execution by a host runtime requires a prepared execution contract, valid policy decision, approved execution ticket, valid signature/trust decision, allowed runner profile, receipt obligation, and, for runtime-consumable SCLite bundles, guarded-strict verification plus replay-fresh status.

The published 0.14.0 alpha line provides records and validators for that boundary. It does not provide the runtime that acts on them.