keelgate.policy

Stability of each symbol (stable or provisional) is listed in the API contract. Narrative and semantics are in the integration contract.

Policy-as-code decision point. Deterministic gate in front of every WRITE.

Decision

Bases: StrEnum

What a policy engine decides: ALLOW, DENY or REQUIRE_APPROVAL.

OpaHttpEngine

Policy engine that asks an OPA server over HTTP (the production default).

Fails closed: any error, timeout or malformed answer is a DENY.

decide_document async

decide_document(
    document: Mapping[str, Any],
) -> PolicyDecision

Evaluate a raw input document. Used by conformance tests and adapters.

policy_version async

policy_version() -> str

Hash of the loaded pack sources, cached for version_ttl seconds.

PolicyAction

Bases: BaseModel

The proposed action a policy judges: the tool, its side effect and capability, and its arguments.

PolicyActor

Bases: BaseModel

Who is acting, as verified from the grant: the agent, the tenant and the grant id.

PolicyContext

Bases: BaseModel

Trusted facts about the world at as_of.

PolicyDecision

Bases: BaseModel

What the policy decided, and exactly which policy decided it.

PolicyEngine

Bases: Protocol

Decides ALLOW / DENY / REQUIRE_APPROVAL for one proposed action.

Implementations must be deterministic functions of policy_input and the loaded policy. They must not consult the wall clock, the network (other than their own decision point) or any model.

PolicyInput

Bases: BaseModel

Everything a policy engine is given: the action, the actor, the resource facts derived from validated arguments, and the trusted context.

Built by Keelgate, never by the model.

to_document

to_document() -> dict[str, Any]

The JSON document handed to the engine.

as_of is rendered as UTC with an explicit +00:00 offset, the one form both OPA and the in-process evaluator parse. NaN and infinity are refused outright (allow_nan=False): they compare false against every limit, which is exactly how a limit check gets bypassed.

RegoEngine

Policy engine that evaluates the same Rego packs in-process.

For tests, the quickstart and single-process use; production should use OPA. Fails closed.

decide_document async

decide_document(
    document: Mapping[str, Any],
) -> PolicyDecision

Evaluate a raw input document. Used by conformance tests and adapters.

decision_from_result

decision_from_result(
    raw: object, *, policy_version: str, engine: str
) -> PolicyDecision

Turn an engine's raw result into a decision, failing closed.

Anything that is not a well-formed {effect, reasons, approval_tier} object with a known effect becomes a DENY. An approval requirement without a usable tier is treated as the strictest tier rather than the loosest.

deny

deny(
    reason: str,
    *,
    engine: str,
    policy_version: str = UNAVAILABLE_VERSION,
) -> PolicyDecision

A fail-closed denial.

hash_sources

hash_sources(sources: Mapping[str, str]) -> str

A stable version hash over named policy sources.

Names are bare file names so the same pack hashes identically whether it is read from disk or fetched back out of a running OPA.

load_pack_sources

load_pack_sources(directory: Path) -> dict[str, str]

Read a pack's .rego sources, excluding *_test.rego.

pack_path

pack_path(name: str) -> Path

Locate a shipped policy pack.

Installed wheels carry packs under keelgate/policy/packs; a source checkout keeps them in policies/ at the repository root.