kernite 0.1.3

Contract-first policy decision CLI for deterministic decision + reason + trace.

Kernite

Kernite is an AI-operable policy decision gateway for write-path enforcement.

It is built for one job: return a deterministic, machine-operable decision contract before any mutation is executed.

Why Kernite

• Contract-first outputs: decision, reason_codes, reasons, trace_hash are stable integration surfaces.
• AI-operable feedback: deny reasons are structured for programmatic remediation, not only human logs.
• Deterministic evidence: same canonical input and policy context produce stable trace_hash output.
• Fail-closed for governed scopes: no matching policy on governed scope returns deny.
• Lightweight runtime: dependencies = [] in pyproject.toml.

Install and Run

uvx kernite serve

Server endpoints:

• GET /health
• POST /execute
• POST /v1/execute
• POST /validate/execute
• POST /v1/validate/execute

/execute and /v1/execute are external PEP entrypoints and always run:

1. payload validation and normalization
2. deterministic policy evaluation

Quick Start: Execute

Request (governed scope with one policy):

{
  "workspace_id": "workspace-demo",
  "principal": {
    "type": "token",
    "id": "api:ops-bot"
  },
  "object_type": "document",
  "operation": "create",
  "payload": {
    "title": "Quarterly Plan"
  },
  "policy_context": {
    "governed": true,
    "selected_policies": [
      {
        "policy_key": "document_create_default",
        "policy_version": 1,
        "effect": "allow",
        "rules": [
          {
            "rule_key": "require_title",
            "rule_definition": {
              "type": "required_fields",
              "fields": ["title"]
            },
            "reason_code": "missing_required_fields",
            "reason_message": "title is required."
          }
        ]
      }
    ]
  }
}

Response shape:

{
  "ctx_id": "ctx_...",
  "message": "Approved by governance policy.",
  "data": {
    "decision": "approved",
    "reason_codes": [],
    "reasons": [],
    "policy_selection_reason_code": "policy_selected_workspace_default",
    "policy": {
      "policy_key": "document_create_default",
      "policy_version": 1
    },
    "trace_hash": "sha256:...",
    "idempotency_key": "..."
  }
}

Policy Context Model

policy_context is optional, but recommended for production integrations.

Main fields:

• governed (bool): whether this request must be enforced as governed scope.
• selected_policies (array): policies selected by your resolver.
• governed_scopes (array): optional scope list (object_type + operation) to infer governed status.
• policy_selection_reason_code (string): explicit selection reason, if already known.

Default behavior:

• governed + no selected policy => denied with no_matching_policy
• not governed + no selected policy => approved with out_of_scope_phase1

PARC Request Model (Cedar-style)

Kernite uses a Cedar-style PARC shape:

• principal
• action (operation)
• resource
• context

This keeps policy evaluation explicit and stable for relationship operations like associate.

See docs/parc-model.md for details and examples.

Use Cases (AI and Non-AI)

• AI-assisted actions: gate tool calls and use reason_codes for automatic retry/remediation.
• Internal APIs: apply one deterministic write guard across UI/API/workers.
• SaaS multi-tenant systems: enforce tenant-scoped write decisions and persist evidence.

Compatibility and Conformance

• Contract policy: docs/compatibility.md
• Conformance vectors: docs/conformance/v1/execute_vectors.json
• Reason code semantics: docs/conformance/v1/reason_codes_v1.json

Objective Performance Check (Python)

Kernite includes a dependency-free benchmark harness.

uv run python benchmarks/benchmark_execute.py --iterations 20000

This gives p50/p95 latency and throughput from your actual environment so language/runtime decisions are based on measured data, not assumptions.

Latest measured snapshot is tracked in docs/performance.md.

Design Philosophy

See docs/design-philosophy.md for rationale on deterministic behavior, minimal runtime surface, and measured optimization strategy.