# 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

```bash
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):

```json
{
  "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:

```json
{
  "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.

```bash
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.
